Agent Execution

When the AI needs to execute code, install dependencies, or interact with tools, it runs inside an isolated container environment. Each execution gets its own environment with controlled access, real-time visibility, and full cost tracking.

Isolated Environments

Every agent execution runs in a dedicated container:

• Docker — used for local development and single-node deployments
• Kubernetes — used in production with resource limits, network policies, and pod security standards (Enterprise build, behind //go:build ee)

By default, agent workflows use per_execution mode — a fresh container is created on dispatch, runs the task, and is torn down when the execution completes. No state persists between executions unless it’s committed back to the repo or saved as an artifact. For latency-sensitive setups you can switch to per_workflow mode, which keeps the container warm across runs at the cost of weaker isolation between executions of the same workflow.

Supported Runtimes

Six pre-built agent images live at ghcr.io/proxifai/agent-images/<name>:latest (source). Reference them by short name in runtime_config.image:

Short name	Description
claude-code	Anthropic’s Claude Code CLI
cursor	Cursor running headless via cursor-agent
copilot	GitHub Copilot CLI
opencode	OpenCode coding agent (ttyd + tmux UI)
aider	Aider terminal coding agent
gemini-cli	Google’s Gemini CLI

All six derive from a shared base image (sshd + tmux auto-attach + repo clone + workflow-script entrypoint) so they expose the same SSH terminal and live tmux view. To use any other tool, set runtime_config.image to a fully-qualified reference like my-registry.example.com/my-image:tag — anything that idles on sleep infinity works because the broker drives commands via docker exec. See Execution modes for the full configuration surface.

Real-Time Streaming

Monitor agent execution as it happens:

• Terminal streaming — watch the agent’s shell output in real-time via WebSocket, rendered with xterm.js
• VNC streaming — for GUI-based agents, view the remote desktop through a noVNC viewer in the browser
• Tab management — open multiple terminal sessions to the same agent simultaneously
• Session persistence — terminal state persists across page navigations within the session

You can also connect to a running agent and execute commands alongside it for debugging or manual intervention.

Cost Tracking

Every execution tracks resource consumption:

• Token usage — input and output tokens broken down by model
• Compute time — container runtime duration in seconds
• Per-execution cost — combined token and compute costs
• Per-workflow cost — aggregate costs across all steps in a workflow
• Team and project rollups — cost summaries at every organizational level

Cost data is available in real-time during execution and in the execution history after completion.

Port Forwarding

When agents start services (web servers, databases, APIs), ports are detected and forwarded automatically:

• Ports are exposed via subdomain routing at {id}-{port}.proxif.ai
• The proxy detects new listeners and creates routes dynamically — no manual configuration required
• WebSocket connections are supported through the same subdomain
• Port forwarding is available for the lifetime of the container

This allows you to interact with running applications — preview a frontend, test an API endpoint, or connect a database client — while the agent is still executing.

Lifecycle

Agent executions follow a defined lifecycle: