Local CIAB Runtime

The local runtime starts each coding-agent session as a subprocess on the API host. Fastest to set up, zero cloud cost, ideal for development and single-user deployments.

Concept: CIAB Overview.

Enable

AGENTCY_FEATURES_CIAB=true
CIAB_RUNTIME=local
CIAB_LOCAL_WORK_DIR=/var/lib/agentcy/ciab
CIAB_LOCAL_SHELL=/bin/bash

CIAB_LOCAL_WORK_DIR is where per-session directories live. Ensure the Agentcy process user has write access.

What happens on session start

1. API allocates a session id and creates <work_dir>/<session_id>/.
2. If seed.repo is provided, shells out git clone (or cp -r for local paths).
3. Spawns the coding-agent binary (default: claude-code if present, otherwise the configured fallback).
4. Sets up a reverse port tunnel: any port the agent binds is exposed via /sandbox/preview/:session_id/:port/, signed with a per-session token.
5. Streams stdout/stderr back over SSE.

Packaged toolchain

The local runtime inherits the host's toolchain — whatever bash, git, node, python, etc. are installed. For consistent agent behavior across hosts, use a pre-provisioned Docker image as the API container:

FROM ghcr.io/agentcy/agentcy-api:latest
RUN apt-get update && apt-get install -y \
  build-essential python3 python3-pip nodejs npm rustc cargo \
  git curl ripgrep jq

Policies and quotas

• CIAB_MAX_SESSIONS_PER_ORG — default 5.
• CIAB_SESSION_IDLE_TIMEOUT — default 900 s; session is killed after this much inactivity.
• CIAB_LOCAL_MAX_MEMORY_MB — enforced via prlimit on supported Linux. Sessions hitting the cap are OOM-killed and marked failed.

Security considerations

The local runtime is not a hard sandbox. The subprocess runs as the same Unix user as the API, with the same file-system view. For untrusted multi-user workloads, use the EC2 runtime.

Hardening options on the local runtime:

• Run the API as a dedicated low-privilege user.
• Mount / read-only; make /var/lib/agentcy/ciab the only writable path.
• Use systemd slices or cgroups v2 to cap CPU/memory.
• Disable outbound egress except to GitHub/provider APIs you trust.
• Block the coding agent from reading secrets (e.g. by not mounting them into the API container at all — pass via env only).

For production multi-tenant, please use EC2 Runtime.

Persistence

Sessions are ephemeral by default. On termination the directory is removed. To persist:

# Create a volume snapshot before terminating
curl -X POST "http://…/ciab-native/sessions/$SID/snapshot" \
  -H "authorization: Bearer $TOKEN" -d '{"label":"wip-payments-fix"}'

Snapshots live in the artifact store (local FS or S3). Restore into a new session:

curl -X POST "http://…/ciab-native/sessions" \
  -H "authorization: Bearer $TOKEN" -d '{"runtime":"local","restore":"snap_…"}'

Troubleshooting

• Coding agent not found. Set CIAB_AGENT_BIN to the absolute path of your claude-code, codex, or wrapper script.
• Port preview 404. Port is being bound to 127.0.0.1 only — tell the agent to bind to 0.0.0.0.
• Permission denied writing to work_dir. The API process user lacks write access. Chown or chmod.

Next

• EC2 Runtime — the production alternative.
• Sandbox & Artifacts — preview URLs and file persistence.
• CIAB Overview