Volc Agent Launchpad

A minimal Agent platform for three-day middleware hackathons. It provides Agent CRUD, a browser Playground, persistent workspaces, and Codex CLI backed by the Volcengine Ark Responses API.

Run it locally with Docker, Colima, or rootless Podman, or deploy it to Volcengine ECS.

Warning

This is a single-user proof of concept. It intentionally has no identity, tracing, audit, or hardened sandbox middleware. Do not use production data or credentials. See SECURITY.md.

Screenshots

Agent Playground

Create an Agent

Features

• React and TypeScript Web UI
• Agent create, edit, start, stop, delete, and multi-turn chat
• Fastify control plane with asynchronous Run state
• Persistent Agent workspaces and Codex sessions
• Disposable Docker, Colima, or Podman container for each local turn
• Docker and Terraform deployment paths for Volcengine ECS

Requirements

• Node.js 22+
• npm 10+
• Docker, Colima, or Podman
• A Volcengine Ark API key and endpoint that supports the Responses API

Codex CLI is included in the Runtime image and is not required on the host.

Local browser SOP

1. Check the local tools

Install Node.js 22+ and one supported container engine, then verify them:

node --version
npm --version
docker --version        # Docker Desktop, Docker Engine, or Colima
podman --version        # Use this instead when running Podman

Only one container engine is required. Codex CLI is already included in the Runtime image.

2. Clone the repository

git clone <repository-url> volc-agent-launchpad
cd volc-agent-launchpad

Skip this step when already working from the repository root.

3. Start the POC

ARK_API_KEY=your-ark-api-key \
ARK_MODEL=ep-your-endpoint-id \
npm run poc

The first run installs Node.js dependencies and builds the Runtime image. The script automatically selects Docker, Colima, or Podman.

4. Open the browser

Visit http://localhost:3000, or open it from the terminal:

open http://localhost:3000       # macOS
xdg-open http://localhost:3000   # Linux desktop

In the Web UI:

1. Select Create Agent.

2. Enter a name, description, and workspace instructions.

3. Select Create Agent again.

4. Enter a task in the Playground, for example:

   Create a TypeScript hello-world CLI, add a test, and run it.
   

The Agent can write files, run commands, and continue the same Codex session in later messages.

5. Stop and resume

Press Ctrl+C in the startup terminal. The script removes temporary Runtime containers but keeps Agent workspaces and conversations.

• macOS state: ~/.volc-agent-launchpad/
• Linux state: .local/
• Custom location: set LOCAL_POC_DATA_ROOT

Run the same npm run poc command to continue later.

Select a specific container engine

Force Podman when multiple engines are installed:

CONTAINER_ENGINE=podman \
ARK_API_KEY=your-ark-api-key \
ARK_MODEL=ep-your-endpoint-id \
npm run poc

Colima uses CONTAINER_ENGINE=docker because it exposes the Docker CLI.

For a clean Linux host, follow the rootless Podman setup.

Docker Compose

Create and edit the configuration:

./scripts/bootstrap-local.sh

Required values in .env:

ARK_API_KEY=your-ark-api-key
ARK_MODEL=ep-your-endpoint-id
APP_AUTH_TOKEN=replace-with-at-least-24-random-characters

Start the application:

docker compose up --build

Open http://localhost:3000. Stop it without deleting Agent data:

docker compose down

Development

npm install
cp .env.example .env
npm install --global @openai/codex@0.111.0
npm run dev

• Web UI: http://localhost:5173
• API: http://localhost:3000

Use local paths in .env when running outside Docker:

APP_DATA_DIR=.data
AGENT_WORKSPACE_ROOT=workspaces
CODEX_HOME=codex-home

Deployment

• Existing Linux ECS with Docker
• Complete Volcengine environment with Terraform
• Local Docker, Colima, and Podman details

The existing-ECS script deploys from the current source tree:

cp .env.example .env.production
./scripts/deploy-existing-ecs.sh .env.production

The Terraform path provisions VPC, subnet, security group, ECS, and EIP:

cp deploy/volcengine/terraform.tfvars.example \
  deploy/volcengine/terraform.tfvars
./scripts/deploy-volcengine.sh

Configuration

Variable	Default	Purpose
ARK_API_KEY	Required	Ark model API key.
ARK_MODEL	Required	Responses-capable endpoint or model ID.
ARK_BASE_URL	Beijing v3 endpoint	Ark OpenAI-compatible API URL.
APP_AUTH_TOKEN	Empty on loopback	Shared demo token; use 24+ random characters remotely.
RUNTIME_PROVIDER	local-process	container for disposable local Runtime containers.
CODEX_SANDBOX_MODE	workspace-write	Codex inner sandbox mode.
CODEX_TIMEOUT_MS	600000	Maximum duration of one turn.
LOCAL_POC_DATA_ROOT	Platform-specific	Local metadata, workspace, and session directory.

See .env.example for all Runtime and resource-limit options.

How it works

flowchart LR
    UI["React Web UI"] --> API["Fastify control plane"]
    API --> Store["JSON metadata and Agent workspaces"]
    API --> Runtime{"Runtime provider"}
    Runtime -->|Local POC| Container["Disposable Docker / Colima / Podman container"]
    Runtime -->|ECS profile| Codex["Codex CLI in application container"]
    Container --> Ark["Volcengine Ark Responses API"]
    Codex --> Ark

Loading

The first turn uses codex exec; later turns resume the stored Codex thread. Deleting an Agent archives its workspace under workspaces/.deleted/.

See docs/ARCHITECTURE.md for component and extension boundaries.

Validation

npm run check
terraform fmt -check -recursive deploy/volcengine
docker compose config

Documentation

• Architecture
• Local POC
• Deployment
• Hackathon extension guide
• Security policy
• Contributing

License

MIT