Skyan

Skyan is an ACP workbench and sandboxed agent runtime for running Codex, Claude Code, Gemini, and custom agents behind one web UI and one normalized event protocol.

It gives you a small TypeScript runtime for:

• connecting to external ACP agents through @agentclientprotocol/sdk;
• running first-party harness agents with pluggable model providers;
• switching between local execution and sandboxed execution;
• streaming chat, tools, permissions, terminal output, files, MCP, and NES activity into one UI;
• hosting the runtime as a gateway, embedding it with the client SDK, or using raw WebSocket events.

Features

• ACP compatible: launches registry-backed ACP CLIs over local stdio or sandbox tunnels.
• Sandbox boundary: supports local mode for desktop use and OpenSandbox mode for isolated execution.
• Unified protocol: maps ACP agents and custom harness agents into the same AgentEvent stream.
• Web workbench: React/Vite UI with agent selection, runtime controls, permissions, tools, terminal, file activity, and session state.
• Gateway included: HTTP/WebSocket server with auth, validation, rate limits, metrics, readiness checks, and optional Redis/Postgres backends.
• Testable core: offline tests cover ACP RPC, ACP mapping, tunnel/auth flows, gateway behavior, local execution, and web state models.

Quick Start

Install dependencies and build:

pnpm install
pnpm build

Run the local workbench with built-in demo agents:

SKYAN_GATEWAY_PORT=4100 \
SKYAN_SERVE_WEB=true \
SKYAN_ENABLE_TEST_AGENTS=1 \
SKYAN_ALLOWED_AGENTS=echo,auth-gate,activity-demo \
SKYAN_EXECUTION_MODE=local \
SKYAN_LOCAL_CWD="$PWD" \
pnpm --filter @skyan/gateway start

Open:

http://localhost:4100/

Useful endpoints:

GET /agents
GET /runtime
GET /healthz
GET /readyz
GET /metrics

Try A Real ACP Agent

Use local mode for CLIs that depend on your local login, browser OAuth, keychain, or shell environment:

SKYAN_GATEWAY_PORT=4100 \
SKYAN_SERVE_WEB=true \
SKYAN_ALLOWED_AGENTS=acp:codex-acp,acp:claude-code,acp:claude-acp,acp:gemini,echo \
SKYAN_EXECUTION_MODE=local \
SKYAN_LOCAL_CWD="/path/to/a/repo" \
pnpm --filter @skyan/gateway start

Then open the web UI and select an agent.

Notes:

• local mode runs agents on your machine and can access real files. Use it for single-user desktop workflows.
• sandbox mode runs agents through OpenSandbox. Use it for hosted or multi-user environments.
• API-key based adapters can receive secrets from gateway env, such as SKYAN_SECRET_OPENAI_API_KEY, SKYAN_SECRET_ANTHROPIC_API_KEY, and SKYAN_SECRET_GEMINI_API_KEY.
• Skyan treats registry auth hints as preflight hints only. Runtime ACP auth events remain the source of truth.

Architecture

Web UI / Client SDK / Raw WS
        |
        | ClientCommand / AgentEvent
        v
Gateway
  auth, validation, rate limits, sessions, metrics, web serving
        |
        v
AgentProvider registry
  |             |              |
  |             |              |
ACP provider   Harness        Demo agents
  |             |
  |             v
  |          ModelProvider
  v
Execution backend
  local process or OpenSandbox container

Core packages:

packages/core          shared events and runtime interfaces
packages/client        WebSocket client SDK
packages/acp-provider  ACP registry, RPC bridge, mapping, auth/runtime controls
packages/gateway       HTTP/WS gateway and web host
packages/harness       first-party model + tool loop
packages/models        model provider abstraction
packages/sandbox       local and OpenSandbox backends
packages/launcher      sandbox-side ACP stdio bridge
web                    React workbench

Configuration

Common environment variables:

env	default	description
SKYAN_GATEWAY_PORT	4000	HTTP/WebSocket port
SKYAN_SERVE_WEB	true	serve the web workbench from the gateway
SKYAN_EXECUTION_MODE	sandbox	sandbox or local
SKYAN_LOCAL_CWD	process cwd	working directory for local execution
SKYAN_ALLOWED_AGENTS	all	comma-separated agent ids
SKYAN_ENABLE_TEST_AGENTS	off	enable demo/test agents
SKYAN_TOKENS	empty	bearer tokens, empty means open dev mode
SKYAN_TOKEN_HASHES	empty	SHA-256 token hashes for hosted deployments
OPENSANDBOX_BASE_URL	http://127.0.0.1:8080	OpenSandbox server
REDIS_URL	empty	shared session caps and rate limits
DATABASE_URL	empty	durable sessions and transcripts

See .env.example for the full list.

Development

pnpm build
pnpm test:unit
pnpm test:acp
pnpm test:client
pnpm test:local
pnpm test:offline

pnpm test:offline is the main no-key validation suite. Real Redis, Postgres, OpenSandbox, and external CLI checks live behind explicit test:real:* commands.

License

MIT