Deployment Guide

Arkloop orchestrates all services via compose.yaml, enabling a full deployment with a single command.

Service Overview

The default startup order is kept by depends_on: postgres → migrate → api/worker, redis → api/gateway/worker. Optional profiles add pgbouncer, redis_gateway (optional performance optimization: Gateway hot-path cache), and seaweedfs only when you ask for them.

Quick Start

1. Prepare Environment Variables

cp .env.example .env

Edit .env and set at least the following required fields:

Generate secure keys:

# JWT Secret (at least 32 characters)
openssl rand -base64 48
 
# Encryption Key (32-byte hex)
openssl rand -hex 32

2. Start All Services

docker compose up -d

The default compose stack now connects directly to postgres and redis, and uses local filesystem storage, which fits single-node deployments. If you want the optional performance layer, set ARKLOOP_DOCKER_DATABASE_URL or ARKLOOP_DOCKER_GATEWAY_REDIS_URL in .env first, then run docker compose --profile performance up -d. If you switch to SeaweedFS or another S3-compatible backend, set ARKLOOP_STORAGE_BACKEND=s3 and run docker compose --profile s3 up -d seaweedfs.

The migrate service will automatically run migrations before api/worker starts and then exit. Check startup status:

docker compose ps

3. Access Services

Internal services stay on the Docker network by default. If you need host-level debugging ports, start with the development override file:

docker compose -f compose.yaml -f compose.dev.yaml up -d

Platform Administrator Initialization

On initial deployment, you can bootstrap a platform_admin user via an environment variable (one-time).

Steps:

1. Register / log in with an account
2. Call GET /v1/auth/me to get the id
3. Set in .env:

ARKLOOP_BOOTSTRAP_PLATFORM_ADMIN=<user_id>

Then restart the api service.

Tool Providers (Optional)

Tools like web_search and web_fetch require backend Provider and credential configuration.

Recommended approach (Universal for SaaS / Self-hosting):

• Log into Console using the bootstrap platform_admin.
• Configure Tool Providers with scope=platform as global defaults.
• For individual tenant customization, override with scope=org.

Compatibility mode (Local quick start only):

• Configure legacy web_search.* / web_fetch.* via environment variables (e.g., ARKLOOP_WEB_SEARCH_PROVIDER, ARKLOOP_WEB_SEARCH_TAVILY_API_KEY).

View Logs

# All services
docker compose logs -f
 
# Specific service
docker compose logs -f api
docker compose logs -f worker
docker compose logs -f gateway

Redeploy (After Code Update)

docker compose build api worker gateway
docker compose up -d

Migrations will automatically re-run before api starts. To force a manual migration run:

docker compose run --rm migrate up

Stop / Clean Up

# Stop, keep data
docker compose down
 
# Stop and remove volumes (reset database)
docker compose down -v

Sandbox rootfs Build

The Sandbox service uses Firecracker microVMs for user code execution, requiring a pre-built rootfs ext4 image.

Build rootfs

cd src/services/sandbox/rootfs
./build.sh

Build artifacts are output to src/services/sandbox/rootfs/output/python3.12.ext4.

Deploy to Target Machine

DEPLOY_HOST=user@host ./build.sh

Default deployment path is /opt/sandbox/rootfs/, override via DEPLOY_PATH.

Pre-installed Environment

Modify pre-installed content: edit src/services/sandbox/rootfs/Dockerfile.python3.12 and rebuild.

Sandbox Deployment

Sandbox supports two backend Providers, switched via sandbox.provider configuration (or ARKLOOP_SANDBOX_PROVIDER environment variable).

Firecracker Mode (Default)

Linux + KVM environment, using microVM isolation:

docker compose --profile firecracker up -d sandbox

Requires /dev/kvm device and Firecracker binary.

Run it with least privilege; privileged is no longer required.

Docker Mode

macOS / Windows (WSL2) / No KVM environment, using Docker container isolation:

# Point to a user-scoped Docker socket
export ARKLOOP_SANDBOX_DOCKER_SOCKET_PATH=/run/user/1000/docker.sock
 
# Start
docker compose --profile docker-sandbox up -d sandbox-docker

Compose will build the local sandbox-agent image from src/services/sandbox/Dockerfile.agent and tag it as arkloop/sandbox-agent:dev by default.

On Linux, prefer the rootless Docker user socket. On macOS / Windows Docker Desktop, use the socket under the user's home directory instead of the system-level /var/run/docker.sock.

sandbox-docker itself stays on the Compose networks, while spawned sandbox-agent containers join the internal arkloop_sandbox_agent network. Host networking is not used.

Local Development (Direct Run)

cd src/services/sandbox
go build -o sandbox-bin ./cmd/sandbox
 
# Docker Mode
ARKLOOP_SANDBOX_PROVIDER=docker \
DOCKER_HOST=unix:///run/user/1000/docker.sock \
ARKLOOP_SANDBOX_SOCKET_DIR=/tmp/sandbox \
ARKLOOP_SANDBOX_TEMPLATES_PATH="" \
./sandbox-bin

Sandbox Configuration

Runtime parameters are configured via Console > Configuration > Sandbox page (written to platform_settings table), or can be overridden with environment variables:

Deployment-level parameters (ENV only, not in Console):

Local Development Mode

During development, you typically run the API on the host machine (for debugging/hot-reloading) while infrastructure runs in Docker:

# Start the minimal infrastructure only
docker compose -f compose.yaml -f compose.dev.yaml up -d postgres redis
 
# Optional performance layer
docker compose -f compose.yaml -f compose.dev.yaml --profile performance up -d pgbouncer redis_gateway
 
# Optional object storage
docker compose -f compose.yaml -f compose.dev.yaml --profile s3 up -d seaweedfs
 
# Run migrations
cd src/services/api
ARKLOOP_LOAD_DOTENV=1 ARKLOOP_DOTENV_FILE=../../.env go run ./cmd/migrate up
 
# Run API on host
ARKLOOP_LOAD_DOTENV=1 ARKLOOP_DOTENV_FILE=../../.env go run ./cmd/api

If you need to use the Gateway, point upstream to the host:

ARKLOOP_GATEWAY_UPSTREAM=http://host.docker.internal:19001 docker compose -f compose.yaml -f compose.dev.yaml up -d gateway

Full Environment Variable Reference

Database

Redis

Storage

Object Storage (Optional SeaweedFS / S3-Compatible)

Authentication & Encryption

API

Gateway

Worker

Telegram channel

Inbound: API webhook; without a public URL, Desktop uses getUpdates polling and the same run / mw_channel_delivery path. In channels.config_json: telegram_typing_indicator (default true), telegram_reaction_emoji (empty disables; if set, reaction is applied to the inbound user message after successful delivery).

Debugging