@vellumai/cli

CLI tools for provisioning and managing Vellum assistant instances.

Installation

This package is used internally by the vel CLI. You typically don't need to install it directly.

To run it standalone with Bun:

bun run ./src/index.ts <command> [options]

Commands

hatch

Provision a new assistant instance and bootstrap the Vellum runtime on it.

vellum hatch [species] [options]

Species

| Species | Description | | ---------- | ------------------------------------------- | | vellum | Default. Provisions the Vellum assistant runtime. | | openclaw | Provisions the OpenClaw runtime with gateway. |

Options

| Option | Description | | ------------------- | ----------- | | -d | Detached mode. Start the instance in the background without watching startup progress. | | --name <name> | Use a specific instance name instead of an auto-generated one. | | --remote <target> | Where to provision the instance. One of: local, gcp, aws, custom. Defaults to local. |

Remote Targets

• local -- Starts the local daemon and local gateway. Gateway source resolution order is: VELLUM_GATEWAY_DIR override, repo source tree, then installed @vellumai/vellum-gateway package.
• gcp -- Creates a GCP Compute Engine VM (e2-standard-4: 4 vCPUs, 16 GB) with a startup script that bootstraps the assistant. Requires gcloud authentication and GCP_PROJECT / GCP_DEFAULT_ZONE environment variables.
• aws -- Provisions an AWS instance.
• custom -- Provisions on an arbitrary SSH host. Set VELLUM_CUSTOM_HOST (e.g. user@hostname) to specify the target.

Environment Variables

| Variable | Required For | Description | | --------------------- | ------------ | ----------- | | ANTHROPIC_API_KEY | All | Anthropic API key passed to the assistant runtime. | | GCP_PROJECT | gcp | GCP project ID. Falls back to the active gcloud project. | | GCP_DEFAULT_ZONE | gcp | GCP zone for the compute instance. | | VELLUM_CUSTOM_HOST | custom | SSH host in user@hostname format. | | VELLUM_GATEWAY_DIR | local | Optional absolute path to a local gateway source directory to run instead of the packaged gateway. | | INGRESS_PUBLIC_BASE_URL | local | Optional fallback public ingress URL when ingress.publicBaseUrl is not set in workspace config. |

Examples

# Hatch a local assistant (default)
vellum hatch

# Hatch a vellum assistant on GCP
vellum hatch vellum --remote gcp

# Hatch an openclaw assistant on GCP in detached mode
vellum hatch openclaw --remote gcp -d

# Hatch with a specific instance name
vellum hatch --name my-assistant --remote gcp

# Hatch on a custom SSH host
[email protected] vellum hatch --remote custom

When hatching on GCP in interactive mode (without -d), the CLI displays an animated progress TUI that polls the instance's startup script output in real time. Press Ctrl+C to detach -- the instance will continue running in the background.

retire

Delete a provisioned assistant instance. The cloud provider and connection details are automatically resolved from the saved assistant config (written during hatch).

vellum retire <name>

The CLI looks up the instance by name in ~/.vellum.lock.json and determines how to retire it based on the saved cloud field:

• gcp -- Deletes the GCP Compute Engine instance via gcloud compute instances delete.
• aws -- Terminates the AWS EC2 instance by looking up the instance ID from its Name tag.
• local -- Stops the local daemon (bunx vellum daemon stop) and removes the ~/.vellum directory.
• custom -- SSHs to the remote host to stop the daemon/gateway and remove the ~/.vellum directory.

Examples

# Retire an instance (cloud type resolved from config)
vellum retire my-assistant