AgentDock

AgentDock is an original, open-source, self-hostable control plane for AI coding agents. It is not an LLM agent. It wraps agents such as Claude Code, Codex, Gemini CLI, OpenHands, LangGraph agents, OpenAI Agents SDK agents, or custom scripts with durable human approvals, task queues, artifacts, policy enforcement, realtime updates, and an append-only audit timeline.

What is in this MVP

• TypeScript monorepo with pnpm workspaces.
• apps/web: Next.js + React + Tailwind accessible UI.
• apps/api: Fastify API with cookie auth, RBAC, rate limiting, CORS, SSE realtime, policy evaluation, and agent tool endpoints.
• packages/db: Prisma schema for PostgreSQL and seed data.
• packages/shared: Zod schemas, shared types, policy evaluator, redaction, approval state machine.
• packages/mcp-server: HTTP JSON-RPC MCP proxy exposing AgentDock tools to agents.
• examples/mock-agent: local script that creates a task, requests approval, polls a decision, uploads an artifact, and completes the task.

Local setup

cd agentdock
cp .env.example .env
pnpm install
pnpm db:generate
pnpm db:push
pnpm db:seed
pnpm dev

Open:

• Web: http://localhost:3000
• API health: http://localhost:4000/health
• MCP proxy health: run pnpm dev:mcp, then http://localhost:4010/health

Demo login after seeding:

demo@agentdock.local
password123!

Docker Compose

cd agentdock
docker compose up --build

Compose starts Postgres, the API, and the web app. The API container runs db:push and db:seed for local MVP convenience.

Database migrations

Prisma schema lives at packages/db/prisma/schema.prisma.

pnpm db:generate          # generate Prisma client
pnpm db:push              # local development sync
pnpm db:migrate           # create/apply reviewed migrations
pnpm db:seed              # demo user, workspace, policies, agent, tasks, approval

An initial SQL migration is included under packages/db/prisma/migrations for review.

Creating an agent token

1. Sign in to the web UI.
2. Open the demo workspace.
3. Go to Agents.
4. Create an agent or rotate an existing token.
5. Copy the token immediately. AgentDock stores only a hash and cannot show it again.

Agent calls must use:

Authorization: Bearer adk_...

Query-string bearer tokens are disabled by default. ALLOW_QUERY_AGENT_TOKEN=true exists only for limited MCP clients and is not recommended.

Running the mock agent

# create or rotate an agent token in the web UI first
AGENTDOCK_AGENT_TOKEN=adk_... pnpm --filter agentdock-mock-agent dev

The mock agent will:

1. Create a task.
2. Request approval for a fake dangerous shell command.
3. Poll for the human decision.
4. Upload a test log artifact.
5. Mark the task completed, or stop after rejection.

Connecting via MCP

Start the API and MCP proxy:

pnpm dev:api
pnpm dev:mcp

Use examples/mcp-config/.mcp.json.example and provide the token through an environment variable or client secret store:

{
  "mcpServers": {
    "agentdock": {
      "url": "http://localhost:4010/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENTDOCK_AGENT_TOKEN}"
      }
    }
  }
}

MCP tools exposed:

• getWorkspaceContext()
• createTask(...)
• updateTaskStatus(...)
• replyToTask(...)
• requestApproval(...)
• getApprovalDecision(...)
• reportProgress(...)
• addArtifact(...)
• getNextTask()
• logEvent(...)

All tool inputs are validated with Zod by the API, scoped to the authenticated agent workspace, and recorded as audit events.

Approval flow

1. Agent calls requestApproval with action details.
2. API evaluates enabled workspace policies.
3. Denied actions return immediately and write an audit event.
4. Required approvals create a pending ApprovalRequest and realtime event.
5. Humans review the full proposed command/tool call/file paths/diff stats in the dashboard.
6. Humans approve, reject, edit, ask for a plan, or escalate.
7. The decision is durably stored with actor, timestamp, reason, and optional edited arguments.
8. Agents poll getApprovalDecision or subscribe to workspace realtime events.

Security model

• Database is the system of record; realtime channels only deliver copies of durable events.
• Every important state transition writes an append-only AuditEvent.
• Agents are scoped to workspaces and authenticated with hashed bearer tokens.
• Raw agent tokens are visible only once and are never logged intentionally.
• Passwords are hashed with bcrypt.
• Minimal RBAC is implemented from the start: owner, admin, reviewer, operator, viewer.
• Auth uses signed HTTP-only cookies for humans.
• Agent tokens must be sent in Authorization: Bearer headers.
• Integration configs are designed to be encrypted with AES-GCM utilities before storage.
• CORS allowlist and rate limiting are enabled.
• All request bodies and MCP tool inputs are validated with Zod.

See SECURITY.md for threat model and hardening guidance.

Tests

pnpm test                 # unit tests; DB integration tests are skipped unless enabled
RUN_DB_TESTS=true pnpm test:integration
pnpm e2e                  # requires seeded DB plus running API/web

Covered units include policy evaluation, token hashing, RBAC checks, approval state transitions, and Zod validation. Integration tests cover workspace creation, agent token creation, task creation, approval request/approve/reject, denied policy rules, and revoked token blocking.

Limitations

• This is an MVP, not a hardened multi-tenant SaaS.
• Invite flows and external integrations are stubbed.
• Agent session creation adapters are minimal; tasks/approvals/artifacts are complete enough for the happy path.
• File uploads use text/file URL fields; object storage can be added later.
• The MCP package is a lightweight HTTP JSON-RPC proxy for AgentDock tools.

Roadmap

• Slack integration
• Discord integration
• GitHub PR integration
• Linear/Jira import
• worktree manager
• Docker sandbox runner
• remote daemon
• OpenAI Agents SDK adapter
• LangGraph interrupt adapter
• OpenHands backend adapter
• mobile push
• multi-reviewer quorum approvals
• signed/tamper-evident audit logs
• OIDC/SAML
• team invites
• policy marketplace
• agent performance analytics