Skip to main content

Namespace

Run and manage Namespace cloud compute instances, containers, commands, ingresses, logs, volumes, and usage.

Categories: Developer Tools, Infrastructure

What you can ask​

  • List the compute instances running in the ci-runners workspace
  • Show the build cache usage for the last 7 days
  • Destroy instances that have been idle for more than 2 hours

Set up​

Namespace connects with credentials from your Namespace account. Have these values ready:

  • Compute region
  • Tenant token
  1. Go to Organization > Connectors and find Namespace.
  2. Click Enable and choose which tools to allow.
  3. Each member enters their own values the first time they use it.

To use one account for the whole organization, turn on Share one connection with everyone. Every member's agents then act as that account, with exactly the access it has.

Tools​

Namespace offers 35 tools. Admins choose which ones agents can use. See Tool permission groups.

Read (27)​

View and search information without changing it.

ToolWhat it does
generate_reportGenerate a per-instance report (resources, peak CPU/RAM use, timing) for instances created in a time range, optionally filtered.
get_artifact_usageGet object storage usage (storage GB-minutes and bytes read) per product, such as the container registry or build caches, for a date range within one month.
get_cache_volumeGet one cache volume generation by ID, including attachment history and cached container images.
get_concurrencyGet current usage and limits (instances, vCPUs, memory) for each concurrency pool.
get_instanceGet one instance's status, shape, deadline, containers, exported URLs and access endpoints.
get_instance_diagnosticsGet diagnostics for an instance, currently its out-of-memory (OOM) kill events.
get_instance_logsGet log lines for one or more instances (running or finished), optionally filtered by container and time range.
get_instance_metricsGet CPU, memory, I/O-wait and storage time series for an instance, optionally within a time range.
get_kubernetes_configGet a kubeconfig for an instance created with Kubernetes enabled (create_instance feature_configuration).
get_network_configurationList the source IP ranges (CIDRs) that this workspace's instances use for outbound traffic, e.g. to allowlist them in a firewall.
get_persistent_volumeGet one persistent volume by ID and tag, including a destroyed one, which list_persistent_volumes no longer returns.
get_ssh_configGet an SSH endpoint, username and host keys for an instance or one of its containers.
get_usageGet compute and build usage (unit and wall minutes) for a date range within one month, in total and per day.
get_usage_time_seriesGet usage over an arbitrary time range as a time series, optionally filtered (platform, shape, GitHub repo/branch) and broken down by a dimension.
get_vnc_configGet the VNC endpoint and username for a macOS instance's desktop; Linux instances return an error.
get_volume_tag_summaryGet the summary for one cache volume tag: size and each generation with its state and attachment.
get_volume_usageGet cache and persistent volume storage usage for a date range within one month.
list_cache_volumesList the workspace's cache volume generations with tag, size, state and which instance each is attached to.
list_ingressesList the public ingresses (names and hostnames) on an instance.
list_instance_egressList outbound connections (domains, resolved IPs, allow/deny decision) an instance made, optionally within a time range.
list_instance_notificationsList the latest lifecycle event (status change) per instance, newest first.
list_instancesList compute instances in the configured region.
list_persistent_volume_snapshotsList the snapshots of one persistent volume, identified by ID or tag.
list_persistent_volumesList persistent (durable) volumes, optionally filtered by tag or site.
list_volume_tag_summariesList one summary per cache volume tag: size and each generation with its state and attachment.
validate_credentialCheck that the Namespace tenant token and compute region work by listing one instance.
wait_instanceBlock until an instance (or one of its containers) is ready, then return its current metadata.

Write (3)​

Create or send data.

ToolWhat it does
create_ingressExpose a port on a running instance through a public HTTPS hostname.
create_instanceCreate a billable compute instance with a shape, optional containers, volumes and ingresses.
start_containersStart more containers on a running Linux instance.

Delete or overwrite (5)​

Remove or replace existing data.

ToolWhat it does
destroy_instancePermanently destroy an instance and its ephemeral state.
destroy_persistent_volume_snapshotDestroy a persistent volume snapshot: Namespace marks it abandoned (abandonedAt) and stops using it as a base for new volumes.
destroy_persistent_volumesPermanently destroy persistent volumes matching either IDs or tags (not both), with their data.
extend_instanceChange when an instance is destroyed: set exactly one of extend_by (add time), ensure_minimum (minimum remaining lifetime) or new_deadline (absolute).
run_commandRun a command on an instance (or one of its containers) and wait for it; returns exit code, stdout and stderr (last 64 KB each).
⌘J