Skip to content
PocketCoder PocketCoder

Backend Reference

pocketbase

Section titled “pocketbase”
import "github.com/qtpi-automaton/pocketcoder/backend"

@pocketcoder-core: Main Orchestrator. Registers hooks, starts the relay, and boots PocketBase. @pocketcoder-core: Sovereign Relay. The orchestration layer that syncs OpenCode with the Sandbox.

Index

Section titled “Index”

func main

Section titled “func main”
func main()

agents

Section titled “agents”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/agents"

@pocketcoder-core: Agent Bundler. Expands agent records into frontmatter-laden bundles.

Index

Section titled “Index”

func GetAgentBundle

Section titled “func GetAgentBundle”
func GetAgentBundle(app *pocketbase.PocketBase, agent *core.Record) (string, error)

GetAgentBundle converts an Agent record into a frontmatter-laden bundle.

func UpdateAgentConfig

Section titled “func UpdateAgentConfig”
func UpdateAgentConfig(app *pocketbase.PocketBase, agent *core.Record) error

UpdateAgentConfig re-assembles the bundle and saves it to the ‘config’ field if changed.

api

Section titled “api”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/api"

@pocketcoder-core: Cron API. Endpoints for Poco to schedule, list, and cancel cron jobs.

@pocketcoder-core: Logs API. Native Docker log streaming via SSE.

@pocketcoder-core: MCP API. Handler for MCP server requests from Poco.

@pocketcoder-core: Authority Evaluator. The custom logic for determining tool permissions.

@pocketcoder-core: Proxy API. Reverse proxy for observability and log services.

@pocketcoder-core: SSH API. Handlers for public key registration and rotation.

Index

Section titled “Index”

func RegisterCronApi

Section titled “func RegisterCronApi”
func RegisterCronApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterCronApi registers the cron task management endpoints.

func RegisterLogsApi

Section titled “func RegisterLogsApi”
func RegisterLogsApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterLogsApi registers the native Docker log streaming endpoints.

func RegisterMcpApi

Section titled “func RegisterMcpApi”
func RegisterMcpApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterMcpApi registers the MCP server request endpoint.

func RegisterPermissionApi

Section titled “func RegisterPermissionApi”
func RegisterPermissionApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterPermissionApi registers the Sovereign Authority evaluation endpoint.

func RegisterProxyApi

Section titled “func RegisterProxyApi”
func RegisterProxyApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterProxyApi registers the reverse proxy endpoints for logs and observability.

func RegisterSSHApi

Section titled “func RegisterSSHApi”
func RegisterSSHApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterSSHApi registers the SSH public key sync endpoint.

func createProxyHandler

Section titled “func createProxyHandler”
func createProxyHandler(target string, prefix string) func(re *core.RequestEvent) error

createProxyHandler creates a standard reverse proxy handler that strips a prefix and forwards to a target.

func resolveHumanUser

Section titled “func resolveHumanUser”
func resolveHumanUser(app *pocketbase.PocketBase, sessionID string) (string, string, error)

resolveHumanUser finds the human user ID and chat ID from an OpenCode session ID.

filesystem

Section titled “filesystem”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/filesystem"

@pocketcoder-core: Artifact API. Secure endpoint for accessing workspace artifacts.

Index

Section titled “Index”

func RegisterArtifactApi

Section titled “func RegisterArtifactApi”
func RegisterArtifactApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterArtifactApi provides a secure window into the /workspace using the PB Filesystem abstraction.

hooks

Section titled “hooks”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/hooks"

@pocketcoder-core: Agent Hooks. Triggers re-bundling when agent records change.

@pocketcoder-core: Cron Hooks. Manages scheduled agent tasks via PocketBase’s built-in cron scheduler.

@pocketcoder-core: LLM Hooks. Handles API key persistence and OpenCode container restart.

@pocketcoder-core: MCP Hooks. Handles MCP server lifecycle, config rendering, and gateway restart.

@pocketcoder-core: Notification Dispatcher. Sends push notifications based on record events and user presence.

@pocketcoder-core: Permission Engine. Registers hooks for auditing and gating record creation.

@pocketcoder-core: SOP Hooks. Seals approved proposals into the governance ledger.

@pocketcoder-core: Timestamp Hooks. Manages created/updated/last_active fields globally.

@pocketcoder-core: Tool Permission Hooks. Renders opencode.json permission + agent blocks and restarts OpenCode.

Index

Section titled “Index”

Constants

Section titled “Constants”

const (
    llmEnvPath        = "/workspace/.opencode/llm.env"
    llmEnvPathShared  = "/llm_keys/llm.env"
    openCodeContainer = "pocketcoder-opencode"
)

const (
    mcpConfigPath     = "/mcp_config/docker-mcp.yaml"
    mcpSecretsPath    = "/mcp_config/mcp.env"
    gatewayContainer  = "pocketcoder-mcp-gateway"
    defaultDockerHost = "tcp://docker-socket-proxy-write:2375"
)

const cronJobPrefix = "pc_cron_"

const (
    openCodeConfigPath = "/workspace/.opencode/opencode.json"
)

func IsUserOnline

Section titled “func IsUserOnline”
func IsUserOnline(app core.App, userID string) bool

IsUserOnline checks if the user has an active Realtime (SSE) connection.

func RegisterAgentHooks

Section titled “func RegisterAgentHooks”
func RegisterAgentHooks(app *pocketbase.PocketBase)

RegisterAgentHooks registers hooks that trigger agent re-bundling.

func RegisterCronHooks

Section titled “func RegisterCronHooks”
func RegisterCronHooks(app core.App)

RegisterCronHooks registers hooks for scheduled agent task management. When a user creates, updates, or deletes a cron job record, this hook syncs the PocketBase cron scheduler accordingly. When a job fires, it creates a message (in an existing or new chat) that the Interface event pump picks up and forwards to OpenCode.

func RegisterGlobalTimestamps

Section titled “func RegisterGlobalTimestamps”
func RegisterGlobalTimestamps(app *pocketbase.PocketBase)

RegisterGlobalTimestamps registers hooks for created, updated, and last_active timestamps.

func RegisterLlmHooks

Section titled “func RegisterLlmHooks”
func RegisterLlmHooks(app core.App)

RegisterLlmHooks registers hooks on the llm_keys collection. When a user saves, updates, or deletes an API key, this hook re-renders the llm.env file and restarts the OpenCode container.

func RegisterMcpHooks

Section titled “func RegisterMcpHooks”
func RegisterMcpHooks(app core.App, openCodeURL string)

RegisterMcpHooks registers hooks for MCP server lifecycle management. When a user approves or revokes an MCP server in the Flutter UI, this hook re-renders the gateway config and restarts the MCP gateway container.

func RegisterNotificationHooks

Section titled “func RegisterNotificationHooks”
func RegisterNotificationHooks(app *pocketbase.PocketBase)

RegisterNotificationHooks registers hooks for triggering push notifications and the /api/push custom endpoint.

func RegisterPermissionHooks

Section titled “func RegisterPermissionHooks”
func RegisterPermissionHooks(app *pocketbase.PocketBase)

RegisterPermissionHooks registers hooks for the permissions collection.

func RegisterPushApi

Section titled “func RegisterPushApi”
func RegisterPushApi(app *pocketbase.PocketBase, e *core.ServeEvent)

RegisterPushApi registers the POST /api/push endpoint. Called by the interface service to send push notifications for task_complete, task_error, and other notification types.

func RegisterSopHooks

Section titled “func RegisterSopHooks”
func RegisterSopHooks(app *pocketbase.PocketBase)

RegisterSopHooks manages the transition from proposal to sealed SOP

func RegisterToolPermissionHooks

Section titled “func RegisterToolPermissionHooks”
func RegisterToolPermissionHooks(app core.App)

RegisterToolPermissionHooks registers hooks that re-render the OpenCode config whenever tool_permissions or ai_agents change.

func SealProposal

Section titled “func SealProposal”
func SealProposal(app *pocketbase.PocketBase, proposal *core.Record) error

SealProposal takes a proposal record, hashes it, and promotes it to the sops ledger. This is the “Master of Signature” implementation where the backend handles integrity.

func SendPushNotification

Section titled “func SendPushNotification”
func SendPushNotification(app core.App, userID, title, message, notifType, chatID string)

SendPushNotification is the unified dispatch function. Flow: rules check -> presence check -> device dispatch

func buildPermissionBlock

Section titled “func buildPermissionBlock”
func buildPermissionBlock(perms []permEntry) map[string]interface{}

buildPermissionBlock converts a list of permission entries into the OpenCode permission format. Tools with only pattern=”*” get flat format (“tool”: “action”). Tools with multiple patterns get nested format (“tool”: {“pattern”: “action”, …}).

func createCronChat

Section titled “func createCronChat”
func createCronChat(app core.App, jobRecord *core.Record, userID string) (string, error)

createCronChat creates a new chat for a cron job execution.

func createCronMessage

Section titled “func createCronMessage”
func createCronMessage(app core.App, chatID string, prompt string) error

createCronMessage creates a user message in the target chat.

func dispatchToDevices

Section titled “func dispatchToDevices”
func dispatchToDevices(app core.App, userID, title, message, notifType, chatID string)

dispatchToDevices sends notifications to every active device registered to the user.

func executeCronJob

Section titled “func executeCronJob”
func executeCronJob(app core.App, jobRecordID string)

executeCronJob is the handler called when a cron job fires. It creates a message in an existing chat or creates a new chat + message, depending on the job’s session_mode.

func isNotificationTypeEnabled

Section titled “func isNotificationTypeEnabled”
func isNotificationTypeEnabled(app core.App, userID, notifType string) bool

isNotificationTypeEnabled checks the user’s notification_rules record. Returns true if the type is enabled or if no rules exist (opt-out model).

func notifyPoco

Section titled “func notifyPoco”
func notifyPoco(app core.App, openCodeURL string, serverName string, status string)

notifyPoco sends a system message to Poco about MCP server status changes.

func renderLlmEnv

Section titled “func renderLlmEnv”
func renderLlmEnv(app core.App) error

renderLlmEnv queries ALL llm_keys records and writes a flat env file.

func renderMcpConfig

Section titled “func renderMcpConfig”
func renderMcpConfig(app core.App) error

renderMcpConfig queries approved MCP servers and writes docker-mcp.yaml and mcp.env to the shared /mcp_config volume. The gateway reads these on startup.

func renderOpenCodeConfig

Section titled “func renderOpenCodeConfig”
func renderOpenCodeConfig(app core.App) error

renderOpenCodeConfig reads the existing opencode.json, patches the permission and agent blocks from PocketBase data, and writes it back.

func restartGateway

Section titled “func restartGateway”
func restartGateway() error

restartGateway sends a restart command to the MCP gateway container via the Docker Socket Proxy.

func restartOpenCode

Section titled “func restartOpenCode”
func restartOpenCode() error

restartOpenCode sends a restart command to the OpenCode container via the Docker Socket Proxy.

func syncAllCronJobs

Section titled “func syncAllCronJobs”
func syncAllCronJobs(app core.App)

syncAllCronJobs queries all enabled cron jobs and registers them with app.Cron().

func syncCronJob

Section titled “func syncCronJob”
func syncCronJob(app core.App, record *core.Record)

syncCronJob registers or removes a single cron job from the scheduler. If the job is enabled, it registers (or re-registers) the cron entry. If disabled, it removes any existing entry.

func updateCronJobStatus

Section titled “func updateCronJobStatus”
func updateCronJobStatus(app core.App, record *core.Record, status string, lastError string)

updateCronJobStatus updates the last_executed, last_status, and last_error fields.

type FcmRelayProvider

Section titled “type FcmRelayProvider”

FcmRelayProvider routes notifications through a Cloudflare Worker relay. The Worker handles subscription verification (RevenueCat), rate limiting (Supabase), and FCM v1 delivery — PocketBase just fires and forgets.

type FcmRelayProvider struct {
    RelayURL string
    UserID   string
    ChatID   string
    Type     string
}

func (*FcmRelayProvider) Send

Section titled “func (*FcmRelayProvider) Send”
func (p *FcmRelayProvider) Send(token, title, body string) error

type NtfyDirectProvider

Section titled “type NtfyDirectProvider”

NtfyDirectProvider sends notifications directly to a UnifiedPush (ntfy) endpoint. This preserves the “Zero-Trust” sovereign architecture.

type NtfyDirectProvider struct {
    ChatID string
    Type   string
}

func (*NtfyDirectProvider) Send

Section titled “func (*NtfyDirectProvider) Send”
func (p *NtfyDirectProvider) Send(endpoint, title, body string) error

type PushProvider

Section titled “type PushProvider”

PushProvider defines the interface for different notification services.

type PushProvider interface {
    Send(token, title, body string) error
}

type permEntry

Section titled “type permEntry”
type permEntry struct {
    tool    string
    pattern string
    action  string
}

permission

Section titled “permission”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/permission"

@pocketcoder-core: Permission Evaluator. Checks requests against whitelisted action patterns.

Index

Section titled “Index”

func Evaluate

Section titled “func Evaluate”
func Evaluate(app core.App, input EvaluationInput) (bool, string)

Evaluate checks if a permission request is whitelisted based on actions.

type EvaluationInput

Section titled “type EvaluationInput”

EvaluationInput represents the data needed to evaluate a permission request.

type EvaluationInput struct {
    Permission string
    Patterns   []string
    Metadata   map[string]any
}

provisioning

Section titled “provisioning”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/provisioning"

Index

Section titled “Index”

func ProvisionSops

Section titled “func ProvisionSops”
func ProvisionSops(app *pocketbase.PocketBase)

ProvisionSops syncs filesystem SOPs into the ‘proposals’ collection. They must still be manually ‘Sealed’ in the ledger to be usable by Poco.

func extractMetadata

Section titled “func extractMetadata”
func extractMetadata(content string) (name, description string)

Simple metadata extractor for YAML frontmatter

func processSopProposal

Section titled “func processSopProposal”
func processSopProposal(app *pocketbase.PocketBase, path string)

utils

Section titled “utils”
import "github.com/qtpi-automaton/pocketcoder/backend/internal/utils"

@pocketcoder-core: Wildcard Matcher. Glob-to-regex pattern matching for permission paths.

Index

Section titled “Index”

func MatchWildcard

Section titled “func MatchWildcard”
func MatchWildcard(str string, pattern string) bool

MatchWildcard implements a simple glob-like pattern matching (e.g. /workspace/**). It converts internal wildcards (*, ?) into regex patterns.

Generated by gomarkdoc