Permissions and security

How Akua keeps agent work scoped, reviewable, and auditable

Agents operate inside a workspace boundary. They do not receive unrestricted credentials, and they do not bypass the same controls used by the dashboard, CLI, and API.

Workspace boundary

Workspace membership, roles, quotas, and billing apply to agent work. If a user or integration cannot access a workspace resource, an agent running for that user or policy should not access it either.

Agents should receive the smallest useful grants for their job. Read access is separate from mutation access.

Grants and approvals

Grants define what an agent is allowed to attempt. Approval requests decide which sensitive actions require a human decision at runtime.

Approval requests map cleanly to ACP permission prompts and Codex-style approvals, but Akua keeps them as durable workspace resources so they can be listed, audited, expired, and resolved from the dashboard or API.

Approvals are not repository change requests. An approval request answers “may this action proceed now?” A repository change request is the durable change artifact: the diff, validation status, review comments, and accept lifecycle. Agents can create or continue change requests without being allowed to accept them.

Examples:

Action	Recommended handling
Read installs, clusters, products, and repository change requests	Grant directly when the agent needs operational context.
Create a repository change request	Grant to change-preparing agents; the change is still reviewable.
Continue an existing repository change request	Grant separately when the agent may attach work to a previous change request or fork.
Accept a repository change request	Require explicit grant and approval.
Run shell commands	Require approval unless the command comes from a tightly controlled automation path.
Use network egress	Deny by default and approve only when needed.
Access secrets	Do not expose secret values to the agent; route access through approved platform actions.

Repository change access

Agents should be allowed to read existing workspace repository change requests when granted. That lets them avoid duplicate work, continue a stale change request, or reuse a fork repository.

Reading change requests does not mean the agent can change or accept them. Mutation actions are separate grants and can be approval-gated.

Provider credentials

Hosted agents call model providers through Akua-controlled routing. The agent runtime sees local provider endpoints and placeholder tokens; real provider credentials are injected outside the agent runtime.

Workspaces can use Akua-managed billing or bring their own provider credentials through workspace secrets. Secret values are not written into agent instructions, events, or retained filesystems.

Provider routing is also the accounting boundary. Each hosted provider request is attributed to the workspace, agent, session, and turn before usage rolls up into budgets and rate limits. Redaction runs before provider metadata is exposed in events or transcript views.

BYOK

Bring-your-own-key mode references workspace secrets by ID. Agents do not receive the raw key. If a credential is disabled, rotated, or missing an enabled version, provider requests should fail before the runtime receives useful access.

Use BYOK when your workspace needs its own provider account, billing relationship, data policy, or model allowlist. Use Akua-managed billing when you want the platform to manage provider credentials and enforce workspace budgets centrally.

Sandbox isolation

Retained runtimes are separate from the Akua control plane. They run with a workspace-scoped session directory and a constrained service identity.

Hosted coding sandboxes should not receive management-cluster credentials, long-lived git credentials, provider keys, or production service secrets. They should use scoped repository tokens, local provider endpoints, and the Akua API/MCP configuration prepared for the current session.

Production sandboxes use additional isolation such as a sandbox node pool, network policy, gVisor runtime isolation, dropped Linux capabilities, and no host-level mounts. If a task does not need files, commands, package managers, or a browser, prefer Code Mode or structured API tools instead of starting a retained runtime.

Prompt-injection boundaries

Agents inspect user repositories, logs, and generated files. Treat all of that content as untrusted input.

Important boundaries:

• Repository files can guide diagnosis, but they do not grant permission to call APIs, reveal secrets, or accept changes.
• Logs and provider responses can be summarized, but secrets and credential-shaped strings are redacted before storage.
• Dashboard widgets can prepare API calls, but the canonical resource API still validates grants, idempotency, If-Match, workspace scope, and approval state.
• Instructions from platform skills and generated sandbox AGENTS.md define the safety rules the harness should follow during code work.

Auditability

Agent work emits events for messages, tool calls, approval requests, approvals, usage, artifacts, and terminal results. These events give users a timeline they can inspect later.

For changes to deployments, repository change requests and git history are the durable record. Full chat transcripts and retained filesystems should expire according to workspace policy unless pinned.

Retention

Keep durable decision records longer than raw runtime state. Repository change requests, git commits, approval decisions, summaries, and audit events are usually cheaper and safer to retain than full transcripts, provider payloads, and retained filesystems.

Retention policy should distinguish:

• Session and event history.
• Provider exchange metadata.
• Artifacts and summaries.
• Approval requests and decisions.
• Repository change requests and git forks.
• Retained runtime filesystems.

Related topics

Sessions and turns

See how work is tracked and streamed.

Agent limits

Review limits that protect workspace spend and runtime usage.