# Permissions

Namespace uses a resource-based permission model. Each API action is associated with a resource type and optionally scoped to a specific resource ID.

The following lists all public resources and their available actions.

# Public Resources

The following resources and actions are publicly available in the Namespace API.

## artifact

Objects stored in a workspace, identified by a path and namespace.

| action | description |
| - | - |
| `create` | Upload a new artifact to the workspace. |
| `expire` | Mark an artifact for deletion. |
| `list` | List artifacts in the workspace. |
| `resolve` | Download or retrieve an artifact. |

## bazel

### bazel/cache

Managed Bazel remote cache for accelerating builds by storing and retrieving build artifacts.

| action | description |
| - | - |
| `ensure` | Provision cache instance and get endpoint credentials. |

### bazel/execution

Managed Bazel remote execution (RBE) clusters for running build and test actions remotely.

| action | description |
| - | - |
| `ensure` | Provision execution cluster and get scheduler/storage endpoints. |
| `get` | Get an existing execution cluster's endpoints. |

## builder

Remote BuildKit instances that perform container image builds on behalf of a workspace.

| action | description |
| - | - |
| `access` | Connect to a running builder instance. |
| `ensure` | Provision or reuse a builder instance. |

## cache

### cache/gradle

Managed Gradle build cache for storing and retrieving build outputs.

| action | description |
| - | - |
| `ensure` | Set up and get Gradle cache endpoint credentials. |
| `read` | Retrieve artifacts from the Gradle cache. |
| `write` | Store artifacts in the Gradle cache. |

### cache/httpcache

Managed HTTP build cache, compatible with Bazel, sccache, and other HTTP-cache-compatible tools.

| action | description |
| - | - |
| `ensure` | Set up and get HTTP cache endpoint credentials. |
| `read` | Retrieve artifacts from the HTTP cache. |
| `write` | Store artifacts in the HTTP cache. |

### cache/turborepo

Managed Turborepo remote cache for storing and retrieving task-level build artifacts.

| action | description |
| - | - |
| `delete` | Delete all cached artifacts for a team. |
| `list` | List teams with cached artifacts. |
| `read` | Retrieve cached artifacts or check cache status. |
| `report` | Submit Turborepo analytics and build events. |
| `write` | Store artifacts in the Turborepo cache. |

## code

### code/repository

Repositories accessible through the workspace's code providers (GitHub or Cursor Origin). Use the canonical HTTPS repository URL ending in `.git` as the resource ID, for example `https://github.com/acme/application.git`. Use `*` to allow all repositories accessible through those providers.

| action | description |
| - | - |
| `read` | Read a repository using Namespace checkout credentials or Git snapshots. |

## containerregistry

Registry-wide configuration, including default and per-repository image expiration policies.

| action | description |
| - | - |
| `configure` | Manage registry expiration policies. |

### containerregistry/domain

Custom registry domains that grant read-only image pull access.

| action | description |
| - | - |
| `pull` | Pull images through a custom registry domain. |

### containerregistry/image

Individual container images within a repository, identified by digest.

| action | description |
| - | - |
| `delete` | Delete a container image by digest. |
| `get` | Get container image details. |
| `list` | List container images across repositories. |
| `update` | Update an image's expiration lifetime. |

### containerregistry/repository

Named image repositories within the container registry.

| action | description |
| - | - |
| `delete` | Delete a repository and its contents. |
| `list` | List image repositories in the registry. |
| `pull` | Pull images from a repository. |
| `share` | Create a publicly accessible link to an image. |
| `unshare` | Revoke public access to a shared image. |

### containerregistry/tags

Tags and tag version history within a repository.

| action | description |
| - | - |
| `list` | List tags in a repository. |

## devbox

| action | description |
| - | - |
| `activate` | Start or resume a devbox session. |
| `create` | Create a new devbox. |
| `expire` | Delete a devbox. |
| `fetch` | Retrieve devbox details. |
| `list` | List devboxes in the workspace. |
| `update` | Update devbox metadata or configuration. |

### devbox/image

| action | description |
| - | - |
| `expire` | Delete or expire a devbox image. |
| `fetch` | Retrieve devbox image details. |
| `list` | List devbox images in the workspace. |
| `wire` | Resolve a devbox image for use. |

## github

### github/runner-profile

Configuration profiles for ephemeral GitHub Actions runners, defining instance shape, OS, cache volumes, and custom runner images.

| action | description |
| - | - |
| `create` | Create a new runner profile. |
| `delete` | Delete a runner profile. |
| `get` | Retrieve a specific runner profile. |
| `list` | List all runner profiles. |
| `update` | Update a runner profile. |

## ingress

Authenticated network access to an instance's exposed ports.

| action | description |
| - | - |
| `access` | Access an instance's exposed ports. |

## instance

Ephemeral compute environments for running containers, with support for Docker, Kubernetes, suspend/resume, and remote access.

| action | description |
| - | - |
| `create` | Create a new instance. |
| `destroy` | Permanently terminate an instance. |
| `dial_host` | Connect to an instance's host services. |
| `exec` | Execute a command inside an instance. |
| `get` | Retrieve an instance's details. |
| `list` | List all instances in the workspace. |
| `refresh` | Extend an instance's lifetime deadline. |
| `release` | Detach an instance from its unique tag. |
| `resume` | Wake a suspended instance. |
| `ssh` | Start an SSH session to an instance. |
| `suspend` | Pause an instance, snapshotting its state. |
| `wait` | Wait for an instance to become ready. |

### instance/ingress

Public internet ingress endpoints exposed from an instance.

| action | description |
| - | - |
| `list` | List ingress endpoints for an instance. |
| `register` | Expose a backend from an instance to the internet. |

### instance/notification

Lifecycle events representing instance status changes, such as running, terminated, or failed.

| action | description |
| - | - |
| `list` | List recent lifecycle events for instances. |

### instance/o11y/egress

Egress requests observed from instance(s).

| action | description |
| - | - |
| `list` | List egress records (per-instance or aggregated) |

### instance/o11y/logs

Streaming and historical log access for instance workloads.

| action | description |
| - | - |
| `get` | Stream or fetch logs from an instance. |

### instance/o11y/metrics

Time-series resource usage metrics for instances, including CPU, memory, I/O, and storage.

| action | description |
| - | - |
| `get` | Retrieve resource usage metrics for an instance. |

### instance/o11y/oom

Out-of-memory (OOM) kill events detected within an instance.

| action | description |
| - | - |
| `list` | List OOM kill events for an instance. |

## network

### network/fabric/segment

Isolated network segments enabling private connectivity between instances.

| action | description |
| - | - |
| `attach` | Connect to a private network segment. |

## tenant

Workspaces in the Namespace platform.

| action | description |
| - | - |
| `get` | Retrieve workspace details and configuration. |

### tenant/builder_config

Builder configuration for a workspace, including default and per-platform build instance types.

| action | description |
| - | - |
| `get` | Retrieve workspace builder configuration. |
| `update` | Update workspace builder configuration. |

### tenant/policies

Policy configuration for a workspace, including compute quotas and feature flags.

| action | description |
| - | - |
| `get` | Retrieve workspace policy settings and quotas. |

### tenant/usage

Compute and storage resource usage tracking for a workspace.

| action | description |
| - | - |
| `get` | Retrieve usage summary for a workspace. |

## testing

### testing/test/logs

Streaming access to test execution logs for a specific test target.

| action | description |
| - | - |
| `stream` | Stream logs for a test target execution. |

### testing/test/result

Individual test target results within a test run, including pass/fail status and duration.

| action | description |
| - | - |
| `list` | List test results within a run. |
| `push` | Submit test results for a target. |

### testing/test/run

Top-level test execution sessions that group individual test results.

| action | description |
| - | - |
| `complete` | Mark a test run as finished. |
| `create` | Start a new test run. |
| `get` | Retrieve details of a test run. |
| `list` | List test runs. |

## token

### token/revokable

Long-lived, explicitly revokable access tokens scoped to a workspace, with a maximum lifetime of 1 year.

| action | description |
| - | - |
| `create` | Create a new revokable access token. |
| `list` | List revokable tokens for a workspace. |
| `refresh` | Ensure a token remains valid for at least a requested duration. |
| `revoke` | Revoke a token to prevent further use. |

## vault

### vault/object

Encrypted secret values stored in a workspace's vault, managed via the Vault API.

| action | description |
| - | - |
| `create` | Create a new vault object. |
| `delete` | Delete a vault object. |
| `describe` | Retrieve a vault object's metadata. |
| `list` | List vault objects in the workspace. |
| `reveal` | Reveal a vault object's decrypted value. |
| `update` | Add a new version to an existing vault object. |

## volume

Cache volumes (and their snapshot generations) used to persist and reuse data across instances and builds.

| action | description |
| - | - |
| `get` | Retrieve details for a cache volume, including destroyed snapshot generations. |
| `list` | List cache volumes and their tag summaries. |

### volume/persistent

Persistent volumes that preserve data independently of instance lifecycles.

| action | description |
| - | - |
| `describe` | Retrieve persistent volume details. |
| `destroy` | Destroy persistent volumes by ID or tag. |
| `list` | List persistent volumes in the workspace.