> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Namespace **Authentication:** Tenant token. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow. ## Sample use cases * 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 ## Available Tools #### create_ingress Expose a port on a running instance through a public HTTPS hostname. Requests need a Namespace token unless an http_m... #### create_instance Create a billable compute instance with a shape, optional containers, volumes and ingresses. Call get_concurrency fir... #### destroy_instance Permanently destroy an instance and its ephemeral state. Cannot be undone. Use list_instances to find instance IDs. #### destroy_persistent_volume_snapshot Destroy a persistent volume snapshot: Namespace marks it abandoned (abandonedAt) and stops using it as a base for new\... #### destroy_persistent_volumes Permanently destroy persistent volumes matching either IDs or tags (not both), with their data. Cannot be undone. Use... #### extend_instance Change when an instance is destroyed: set exactly one of extend_by (add time), ensure_minimum (minimum remaining life... #### generate_report Generate a per-instance report (resources, peak CPU/RAM use, timing) for instances created in a time range, optionall... #### get_artifact_usage Get object storage usage (storage GB-minutes and bytes read) per product, such as the container registry or build cac... #### get_cache_volume Get one cache volume generation by ID, including attachment history and cached container images. Use list_cache_volum... #### get_concurrency Get current usage and limits (instances, vCPUs, memory) for each concurrency pool. Check before create_instance to se... #### get_instance Get one instance's status, shape, deadline, containers, exported URLs and access endpoints. Credentials are omitted... #### get_instance_diagnostics Get diagnostics for an instance, currently its out-of-memory (OOM) kill events. Use when an instance or container die... #### get_instance_logs Get log lines for one or more instances (running or finished), optionally filtered by container and time range. Pagin... #### get_instance_metrics Get CPU, memory, I/O-wait and storage time series for an instance, optionally within a time range. Use list_instances... #### get_kubernetes_config Get a kubeconfig for an instance created with Kubernetes enabled (create_instance feature_configuration). Client cred... #### get_network_configuration List the source IP ranges (CIDRs) that this workspace's instances use for outbound traffic, e.g. to allowlist them in... #### get_persistent_volume Get one persistent volume by ID and tag, including a destroyed one, which list_persistent_volumes no longer returns... #### get_ssh_config Get an SSH endpoint, username and host keys for an instance or one of its containers. The private key is REDACTED unl... #### get_usage Get compute and build usage (unit and wall minutes) for a date range within one month, in total and per day. Defaults... #### get_usage_time_series Get usage over an arbitrary time range as a time series, optionally filtered (platform, shape, GitHub repo/branch) an... #### get_vnc_config Get the VNC endpoint and username for a macOS instance's desktop; Linux instances return an error. The password is RE... #### get_volume_tag_summary Get the summary for one cache volume tag: size and each generation with its state and attachment. Use list_volume_tag... #### get_volume_usage Get cache and persistent volume storage usage for a date range within one month. Defaults to the current month. #### list_cache_volumes List the workspace's cache volume generations with tag, size, state and which instance each is attached to. The API r... #### list_ingresses List the public ingresses (names and hostnames) on an instance. Use list_instances to find instance IDs. #### list_instance_egress List outbound connections (domains, resolved IPs, allow/deny decision) an instance made, optionally within a time ran... #### list_instance_notifications List the latest lifecycle event (status change) per instance, newest first. Optionally filter by instance IDs from li... #### list_instances List compute instances in the configured region. By default only PENDING, CREATING and RUNNING instances; set include... #### list_persistent_volume_snapshots List the snapshots of one persistent volume, identified by ID or tag. Use list_persistent_volumes to find them. A sna... #### list_persistent_volumes List persistent (durable) volumes, optionally filtered by tag or site. Paginate with page_info.cursor. Persistent vol... #### list_volume_tag_summaries List one summary per cache volume tag: size and each generation with its state and attachment. The API returns all ta... #### run_command Run a command on an instance (or one of its containers) and wait for it; returns exit code, stdout and stderr (last 6... #### start_containers Start more containers on a running Linux instance. Namespace has no API to stop a single container; destroy_instance... #### wait_instance Block until an instance (or one of its containers) is ready, then return its current metadata. Times out after 45 sec...