Docker Compose with Agent Sandbox

Stib can launch each eligible card session in a short-lived agent container. This separates the agent process from the server database and from repositories that are not mounted into that container.

This is an advanced deployment. Container isolation reduces accidental reach but does not make arbitrary code risk-free: the agent still writes the selected project, uses configured credentials, reaches allowed networks, and talks back to Stib.

Requirements

• Stib Server itself runs in Docker.
• The server can reach a Docker API through DOCKER_HOST or /var/run/docker.sock.
• STIB_AGENT_IMAGE points to a compatible agent-runtime image.
• Project directories are mounted into the server at the same absolute host path used when spawning agent containers.
• Agent and server image tags use the same Stib protocol version.

The server reports sandbox capability in project settings. A native server or a container without Docker API access cannot enable the project toggle.

Safer socket access

Prefer a dedicated socket proxy over mounting the raw Docker socket. The proxy still permits container creation and deletion and therefore remains a powerful control plane. Restrict it to a private network and never publish its port.

services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:0.3.0
    restart: unless-stopped
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      IMAGES: 1
      POST: 1
      DELETE: 1
      ALLOW_START: 1
      ALLOW_STOP: 1
      NETWORKS: 0
      VOLUMES: 0
      EXEC: 0
    networks:
      - stib-control

  stib:
    image: enixion/stib-server:${STIB_VERSION}
    restart: unless-stopped
    depends_on:
      - docker-socket-proxy
    ports:
      - "50505:50505"
    volumes:
      - stib-data:/data
      # Replace this path, keeping host and container sides identical.
      - /srv/stib-projects:/srv/stib-projects:rw
    environment:
      RUST_LOG: info
      DOCKER_HOST: tcp://docker-socket-proxy:2375
      STIB_AGENT_API_URL: http://host.docker.internal:50505
      STIB_AGENT_IMAGE: enixion/stib-agent-runtime:${STIB_VERSION}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - stib-control
      - default
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:50505/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3

networks:
  stib-control:
    internal: true

volumes:
  stib-data:

Set STIB_VERSION in a Compose .env file to one version published for both images. Pull both before updating:

docker compose pull
docker compose up -d

Enable a project

1. Start the stack and confirm /api/health.
2. Open Project settings → General → Environment.
3. Confirm that the repository path is accessible and the Sandbox toggle is enabled.
4. Turn Sandbox on for a test project.
5. Run a harmless card and inspect server logs plus docker ps while it executes.

Do not enable the project until the server path is the intended host path. A wrong mount can expose no files—or the wrong files—to the agent.

Callback URL

STIB_AGENT_API_URL selects the private route used by the agent runtime to call back to the server. The provider process receives the resolved route as STIB_API_URL, which remains the CLI contract. The server's configured public origin is never reused implicitly. On Linux, the host-gateway mapping above makes host.docker.internal resolve. On a custom network topology, replace the internal origin with one reachable from agent containers but not exposed unnecessarily to the public internet.

Remote callback tokens are loopback/private-network restricted. Do not use STIB_ALLOW_REMOTE_CALLBACK to expose callbacks to an untrusted network.

Verify isolation

Use a disposable project and verify:

• the agent can read/write only the intended project paths for its column mode;
• an unrelated repository and the server /data volume are absent;
• the callback succeeds and conversation events arrive;
• cancellation removes the agent container;
• files have usable ownership on the host;
• orphan containers from an interrupted server are reconciled safely.

The currently configured agent image determines which provider executables exist inside the sandbox. A credential visible in Stib is not sufficient if its runtime is absent from that image.

Operational cautions

• Back up Stib before upgrading server and agent images together.
• Pin versions in production; do not let one image advance independently.
• Monitor orphan containers and disk use without deleting containers from another Stib instance.
• Treat the socket proxy, mounted repositories, provider credentials, and callback origin as security-sensitive configuration.

Next: Docker Compose and Server Configuration.