AgentCloud

A control plane for persistent AI workers. Turn an objective into a versioned worker, test it without writes, deploy it to a durable runtime, require human approval for sensitive actions, and inspect every decision in one timeline.

Project overview · Interactive demo · Architecture · Security · Deployment · Implementation plan

What AgentCloud does

Most agent demos end when the chat closes. AgentCloud treats an AI worker as a durable, governed software artifact:

Related MCP server: GCP MCP Server

Quickstart

Requirements

• Node.js 24 or later

• pnpm 11

Install and run

git clone https://github.com/premhiru/agentcloud.git
cd agentcloud
pnpm install
cp .env.example .env.local
pnpm dev

On PowerShell, replace the copy command with:

Copy-Item .env.example .env.local

Open http://localhost:3000. The checked-in environment template already enables the safe demo adapters, so no database or vendor credentials are required.

Demo state is persisted in .agentcloud/demo-store.json. Demo mode is explicit and is never used as a production fallback.

Run the canonical worker

The included Inbound Sales Worker demonstrates the complete governed lifecycle:

1. Open Workers and select Inbound Sales Guardian.

2. Choose Test safely. AgentCloud reads deterministic lead fixtures and records proposed writes without executing them.

3. Deploy the worker, then choose Run now.

4. The run qualifies the lead, updates the fake CRM once, drafts outreach, and pauses before sending email.

5. Open Approvals, inspect the exact redacted action, then choose Approve and view run.

6. The same run resumes from its checkpoint, sends exactly one fake email, posts one fake Slack notification, and finishes with a complete timeline.

7. Pause or resume the deployment, create a new version, deploy it, and roll back to a previous immutable version.

The same sequence is covered through the AgentCloud MCP, including reconnecting from a new client after the initiating client has closed.

How it works

Dashboard · MCP · Signed webhooks
                │
                ▼
      AgentCloud control plane
                │
     ┌──────────┼──────────┐
     ▼          ▼          ▼
 WorkerSpec   Policy     Budgets
 versions     engine     and usage
     │          │          │
     └──────────┼──────────┘
                ▼
        Governed worker runner
                │
      ┌─────────┴─────────┐
      ▼                   ▼
 WorkerRuntime     IntegrationAdapter
 Fake / Trigger.dev  Fake / Composio
                │
                ▼
 PostgreSQL · approvals · timelines · audit

AgentCloud keeps vendor-specific code behind narrow interfaces:

This separation keeps the core lifecycle portable and makes CI deterministic.

WorkerSpec and authority

A worker deployment references an immutable WorkerSpec version. The spec defines identity, triggers, authority, budgets, memory policy, and runtime behavior without embedding credentials. This excerpt shows the authority and budget shape:

schemaVersion: "1.0"
identity:
  name: Inbound Sales Guardian
capabilities:
  - capability: gmail.search_messages
  - capability: hubspot.upsert_contact
  - capability: gmail.send_email
authority:
  defaultEffect: deny
  rules:
    - capability: gmail.search_messages
      effect: allow
    - capability: hubspot.upsert_contact
      effect: allow
    - capability: gmail.send_email
      effect: require_approval
budget:
  monthlyUsd: 50
  perRunUsd: 1
  maxModelCallsPerRun: 12
  maxToolCallsPerRun: 30

The policy engine evaluates every tool call against the pinned spec. Missing capabilities, invalid inputs, exceeded budgets, and unknown operations fail closed.

Safety model

Safety is enforced in application code and persistence—not delegated to the model prompt.

See SECURITY.md for the complete threat model and security invariants.

MCP

AgentCloud exposes a Streamable HTTP MCP endpoint at:

https://YOUR_DOMAIN/api/mcp

Production MCP authentication uses Clerk OAuth metadata and organization membership. Each tool rechecks its required scope server-side.

Available lifecycle tools include:

create_worker       update_worker       test_worker
deploy_worker       trigger_worker      cancel_run
get_run             list_runs           list_approvals
approve_action      reject_action       pause_worker
resume_worker       list_worker_versions rollback_worker
get_usage           list_connections    delete_worker

OAuth scopes:

workers:read        workers:write       workers:deploy
runs:read           approvals:read      approvals:write
connections:read

The protocol tests use the official MCP client in-process, enforce authentication and scopes, and verify that a second client can recover persisted workers and runs.

Webhooks

Workers can expose signed webhook triggers at:

POST /api/webhooks/workers/{workerId}/{triggerKey}

Requests require:

• X-AgentCloud-Signature: sha256=<hex> computed from the raw body with WEBHOOK_SIGNING_SECRET

• A stable Idempotency-Key

• A body no larger than 256 KiB

Webhook requests are rate-limited, structurally validated, tenant-scoped, and deduplicated. Reusing an idempotency key with a different payload is rejected.

Configuration

AgentCloud has two explicit operating modes:

Start with .env.example, which documents every variable and its safe default. Never expose server secrets through NEXT_PUBLIC_* variables.

Development

pnpm dev               # Next.js development server
pnpm lint              # ESLint with zero warnings
pnpm typecheck         # strict TypeScript
pnpm test              # full Vitest suite
pnpm test:unit         # domain and adapter tests
pnpm test:integration  # persistence and lifecycle tests
pnpm test:security     # product safety invariants
pnpm test:mcp          # authenticated MCP lifecycle
pnpm test:e2e          # critical Playwright journeys
pnpm build             # optimized production build
pnpm db:migrate        # apply committed migrations
pnpm db:seed           # seed a local tenant
pnpm trigger:dev       # Trigger.dev local task runner
pnpm trigger:deploy    # deploy Trigger.dev tasks

Validation contract

CI runs the following against Node.js 24, pnpm 11, and PostgreSQL 16:

pnpm install --frozen-lockfile
pnpm db:migrate
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e

The test matrix covers unit, integration, tenant-isolation, dry-run safety, approval pause/resume, duplicate-side-effect, MCP lifecycle, signed webhook, production persistence, and critical browser flows.

Repository guide

src/
  application/       control plane and durable demo store
  domain/            WorkerSpec, versions, policy, budgets
  runtime/           governed runner and runtime adapters
  integrations/      tool registry and integration adapters
  approvals/         approval hashing, decisions, and waitpoints
  persistence/       PostgreSQL repositories and audit records
  mcp/               authenticated MCP server and tool service
  app/               dashboard, API, MCP, and webhook routes
tests/
  unit/              domain contracts
  integration/       persistence and lifecycle boundaries
  security/          non-negotiable product invariants
  mcp/               protocol-level lifecycle tests
  e2e/               Playwright user journeys
trigger/              Trigger.dev durable task entrypoint
agentcloud-site/      companion product site

Production deployment

Deploy the web application and runtime from the same Git revision:

1. Provision PostgreSQL or Neon and run the committed migrations.

2. Configure Clerk Organizations and MCP OAuth scopes.

3. Configure Trigger.dev and deploy the worker task.

4. Create Composio Gmail, HubSpot, and Slack auth configurations.

5. Configure OpenAI, the application URL, and webhook signing secret.

6. Deploy the Next.js application to Vercel, then run the operational checks.

The exact release order, smoke tests, rollback procedure, and credential-dependent checks are in DEPLOYMENT.md.

Project status

The credential-independent MVP and all milestones in PLAN.md are complete. PROGRESS.md records the implemented behavior and verification evidence for each milestone.

Real Gmail, HubSpot, Slack, Clerk OAuth, Trigger.dev Cloud, OpenAI, and Vercel checks remain operator-credentialed deployment steps. The product intentionally does not expose financial, destructive, bulk, arbitrary MCP, browser, shell, or user-code tools.

Documentation

• ARCHITECTURE.md — boundaries, core contracts, persistence, and runtime independence

• SECURITY.md — threat model, tenant isolation, approvals, side effects, and vulnerability reporting

• DEPLOYMENT.md — production provisioning, release, verification, and rollback

• docs/MCP_REGISTRY.md — remote MCP OAuth gates and guarded Registry publication

• docs/LAUNCH_KIT.md — positioning, launch copy, and the verified 75-second demo script

• CONTRIBUTING.md — development workflow, safety guardrails, and test expectations

• PLAN.md — product thesis, technical design, milestones, and Definition of Done

• PROGRESS.md — milestone checkpoints and exact verification history

• .env.example — complete configuration contract

Security

Do not open a public issue containing a vulnerability, credential, customer data, or unredacted action payload. Follow the private reporting guidance in SECURITY.md.

License

AgentCloud is available under the Apache License 2.0.