maka-agent-cloud

maka-agent-cloud is the Go control plane for Maka Cloud Agents. It will own durable Cloud Session identity, Activation admission and deduplication, leases, checkpoint compare-and-swap, sandbox lifecycle, and committed-result publication.

The Maka process inside a sandbox remains the execution plane and runs exactly one Activation at a time.

Status

The repository contains the PostgreSQL-authoritative SandboxAttempt reconcile slice: atomic resource/change/outbox persistence, at-least-once Hatchet dispatch, tenant-scoped workers, and OpenSandbox adoption after ambiguous provider outcomes. The broader Cloud Agent API remains under development.

Layout

api/proto/              Future versioned control-plane contracts
cmd/maka-agent-cloud/         Process entry point
internal/app/           Dependency composition and process lifecycle
internal/config/        Environment-backed configuration
internal/controller/    Idempotent resource reconciliation loops
internal/publisher/     Post-commit result delivery
internal/resource/      Internal resource model
internal/sandbox/       Sandbox-provider boundary
internal/scheduler/     Sandbox placement policy
internal/store/         Resource, lease, and bundle repository ports
internal/transport/grpc gRPC transport and standard health service
docs/                   Architecture research and decisions

The V1 architecture is specified in docs/architecture-v1.md. Domain and persistence packages stay behind application interfaces and do not import transport types. The first Maka Graph implementation plan is in docs/implementation-graph-v1.md. The PostgreSQL/Hatchet reconciliation boundary and downstream package ownership are specified in docs/reconcile-workflow-contract.md.

Run

Default tests need no external services:

go test ./...

Start the complete local environment (PostgreSQL, Hatchet, migrations, API, worker, and fake OpenSandbox) with:

make dev

To start only PostgreSQL and Hatchet, use make dev-up.

The server listens on :8080 by default. Override it with:

MAKA_CLOUD_GRPC_ADDR=127.0.0.1:9090 make run

Production process setup, migrations, worker startup, and opt-in PostgreSQL and Hatchet smoke tests are documented in docs/local-development.md.

RFC

The project follows maka-agent/maka-agent#1286:

checkout -> create sandbox -> hydrate -> activate -> pack
         -> CAS commit -> publish reply -> destroy sandbox