Skip to main content

Core concepts

This page explains the six ideas everything else on the platform is built on. One running example threads through it: Priya, an engineer at Acme, ships a support agent with her teammate Sam, wires up CI, and never once files a ticket to understand her own permissions.

Organizations and projects​

An organization is the top-level container — usually a company. Acme is an organization.

A project is a private workspace inside an organization. Everything you create — agents, functions, secrets, topics, vector indexes — lives inside exactly one project, isolated from every other project with its own members, network boundary, and quota. Acme has a project called ml-team, and that's where Priya works.

Every project gets an immutable short id (for example ab12cd) that appears in its namespace (cai-p-ab12cd) and in public URLs (https://my-agent-ab12cd.apps.codyhill.dev). Renaming a project never changes its short id — so renames never break a running workload or a bookmarked URL. That's a deliberate promise.

Roles: the two-axis model​

Most clouds have one ladder of permissions. This platform has two separate axes, and understanding them explains every "why can't I see this?" moment:

  • Metadata authority — power over the project object: rename it, delete it, manage who's a member.
  • Resource authority — power over the project's contents: agents, functions, secrets, data.

The roles, in plain words:

RoleMetadata authorityResource authority
Project membernoneuse the project's resources
Project adminmanage this project and its memberseverything, including delete, reveal, and minting credentials
Org adminadmin on every project in their orgadmin on every project in their org (inherited, live)
Platform admineverywherenowhere

Read that last row again, because it's the platform's signature idea: the people who operate the platform cannot read your project's contents. A platform admin can see that ml-team exists and manage its membership, but its agents, secrets, and conversations return "not found" to them.

When a platform admin genuinely needs inside — say, to repair something broken — they must take a break-glass grant: a self-granted, temporary membership that requires a written reason, appears in the project's member list for everyone to see, expires on its own (4 hours by default, 24 maximum), and is recorded in the audit log. There is no quiet path in. Details in Break-glass and audit.

One related behavior that surprises people: if you have no grant at all on a project, its API paths return 404 not found — never 403. The platform won't even confirm the project exists. You only see 403 once you're inside but lack the role for a specific action.

In our example: Priya is admin on ml-team, Sam is member. Sam can deploy and invoke agents; Priya can additionally add members, delete things, and mint credentials. Dana, a platform admin at Acme's provider, can see the project exists — and nothing inside it.

API keys and service accounts​

Signing in gives you a session token that lasts 12 hours — fine for humans, useless for a CI pipeline. For machines there are API keys: long-lived credentials that look like cai_<keyid>_<secret> and go in the Authorization: Bearer header (or the CLI's $CAI_TOKEN).

Two kinds of principal can hold one:

  • A personal key acts as you. Your permissions are re-checked live on every request, so if you lose a role, your key loses it on its very next call.
  • A service account is a machine identity that belongs to one project, with an email-style name like ci-deploy@ab12cd.cai.local and a project role of its own. Its authority never extends past its project's contents.

Priya creates a service account ci-deploy with the member role and mints a key for it. Her GitHub Actions workflow exports the key as $CAI_TOKEN and runs platformctl deploy — no human credentials in CI, and revoking that one key ends exactly that one access.

Three sharp edges, stated plainly:

Keys are shown once

The full secret appears in exactly one API response, at creation. Only a hash is stored — nobody, including support, can show it again. If it's lost, revoke it and mint another.

  • A service account cannot create or manage credentials — a leaked CI key can't mint replacement keys for itself, which is what makes revoking it meaningful.
  • Revocation is immediate: the next request presenting a revoked key is refused.

Manage all of this in the console — see Service accounts and API keys — and see API authentication for the full credential model.

Quotas​

Every project has caps on what it can consume: running instances, services, CPU, and memory. Fresh projects start with defaults (50 running instances, 30 services, 10 CPU / 20Gi reserved, 20 CPU / 40Gi maximum). A cap of 0 means unlimited.

Quotas are read-only and live: the console's Quotas page and the quota API show real usage against real limits, straight from enforcement — green under 70%, amber to 90%, red above. Raising a cap is an administrator action, not an API call.

Quotas fail loudly, not mysteriously. When ml-team is at its service limit and Sam tries to deploy one more function, the deploy is refused up front with:

this project is at its service limit (30 / 30): deploying needs at least one
more service and cannot proceed. Delete an agent or function, or ask an admin
to raise the project's service quota, then deploy.

See Quotas and audit and the full limits reference.

Scale-to-zero​

Workloads on this platform don't idle — they stop. A few minutes after the last request, an agent or function scales down to zero running instances. It costs no capacity while idle, and it doesn't count against the project's running-instances quota while at zero. The next request cold-starts it: the platform spins an instance back up, which makes that first response noticeably slower than the ones that follow.

Priya's support agent gets traffic during business hours and sits at zero overnight. Nobody turns anything off; nobody turns anything back on.

If a cold start is unacceptable for a given workload — a demo, a latency-sensitive endpoint — you can set minimum instances to 1 in the workload's configuration to keep one warm, at the cost of it always occupying quota. The mechanics live in Autoscaling and scale-to-zero.

Data plane vs. management plane​

The platform draws a hard line between two kinds of request:

  • The management plane is everything that creates, changes, or inspects state: deploy, delete, logs, secrets, membership, keys. It always requires a credential.
  • The data plane is talking to a deployed agent or function — invoke. On the control plane's invoke route it is open by default: your agent's users don't need platform accounts, which is what makes it possible to put an agent behind a public chat widget. Platform operators can close it (an install-level setting) if a deployment demands it.

There is a second thing "open" could mean, and the platform is deliberately strict about it: your workload itself is private by default. A newly deployed agent or function is marked cluster-local, so the authenticated control plane is the only route to it, and the https://<name>-<project-short>.apps.codyhill.dev address is reserved but not served. Publishing is an explicit opt-in, because a published workload is reachable from the internet with no sign-in and no rate limit — which would let anonymous callers spend your model budget. See invoke your agent for how to publish one on purpose.

The one deliberate exception: writing to an agent's long-term memory always requires authentication, even when invoke is open — because memories are read back into other callers' conversations later. The API says it best:

memorize requires authentication: it writes durable memory that later callers
read back. Invoke without 'memorize', then call
POST /v1/agents/{name}/sessions/{id}/memorize with a session token.

So in our example: Acme's customers chat with the support agent anonymously (data plane), while Priya, Sam, and the ci-deploy service account authenticate for everything else (management plane). And every management-plane change — each deploy, each key minted, each member added, even Dana's hypothetical break-glass grant — lands in the project's audit log, readable by every member, newest first.

Full details in Invoking agents and Security overview.

The whole model on one card​

ConceptThe one thing to remember
OrganizationOwns projects and users; usually your company.
ProjectThe isolation unit. Everything lives in exactly one. Its short id never changes.
Metadata vs. resource authorityControlling a project's existence and membership is separate from touching its contents.
Platform adminRuns the platform; can see your project exists, cannot see inside it without visible break-glass.
404 ruleNo grant on a project means 404, never 403 — existence is not disclosed.
Session token12 hours, for humans.
API keycai_..., long-lived, shown once, revoked instantly, for machines.
Service accountA machine identity locked to one project; can never mint credentials.
QuotaLive, visible, and loud when hit; raising it is an admin action.
Scale-to-zeroIdle workloads stop; the next request cold-starts them.
Data planeInvoking agents — open by default, no platform account needed.
Management planeChanging anything — always authenticated, always audited.

Next steps​