Skip to main content
Namespaces enable small teams to share a single public HAPI hub while maintaining complete isolation of sessions, machines, and user data. Each team member uses a different namespace to isolate their resources without running separate hub instances.
Namespaces are an advanced feature for specific deployment scenarios. Most users should run their own hub instance instead.

​
How Namespaces Work

The hub uses a single base CLI_API_TOKEN for authentication. Clients append :<namespace> to the token to create isolated workspaces within the same hub instance.

Hub Configuration

Configure only the base token without any namespace suffix

Client Configuration

Each user appends their unique namespace to the base token

​
Setup

​
1. Configure the Hub

On the hub server, set only the base token without any namespace: 
export CLI_API_TOKEN="your-base-token"
The hub-side CLI_API_TOKEN must NOT include a :<namespace> suffix. If it does, the hub will strip the suffix and log a warning.

​
2. Configure Client Tokens

For each user, append a unique namespace to the base token: Alice’s configuration: 
export CLI_API_TOKEN="your-base-token:alice"
Bob’s configuration: 
export CLI_API_TOKEN="your-base-token:bob"

​
3. Web Login and Telegram

When using web login or binding Telegram accounts, always use the full base:namespace token format: 
# Web login
hapi auth login
# Enter: your-base-token:alice

# Telegram binding
# Use: your-base-token:alice when prompted in the Mini App

​
Use Cases

A team of 3-5 developers sharing a single VPS or cloud instance. Each developer gets their own namespace for complete isolation while sharing infrastructure costs.
Use different namespaces for development, staging, and testing environments on the same hub instance.
Agencies managing multiple client projects can use namespaces to separate client sessions on a single hub.

​
Namespace Isolation

Namespaces provide complete isolation of:
  • Sessions: Each namespace has its own set of AI coding sessions
  • Machines: Machine registrations are namespace-scoped
  • Users: Telegram bindings and web users are isolated per namespace
  • Data: All session data, messages, and metadata are namespace-scoped
Sessions, machines, and users in one namespace are completely invisible to other namespaces.

​
Limitations and Gotchas

​
Machine ID Conflicts

One machine ID cannot be reused across namespaces. To run multiple namespaces on the same physical machine, you have two options: 
# Alice's environment
export HAPI_HOME=~/.hapi-alice
export CLI_API_TOKEN="your-base-token:alice"

# Bob's environment
export HAPI_HOME=~/.hapi-bob
export CLI_API_TOKEN="your-base-token:bob"

​
Remote Spawn Limitations

Remote spawn (via the HAPI runner) is namespace-scoped. If you need remote spawning for multiple namespaces on the same machine, run a separate runner per namespace using different HAPI_HOME directories. 
# Alice's runner
export HAPI_HOME=~/.hapi-alice
export CLI_API_TOKEN="your-base-token:alice"
hapi runner start

# Bob's runner (in a different terminal)
export HAPI_HOME=~/.hapi-bob
export CLI_API_TOKEN="your-base-token:bob"
hapi runner start

​
Token Format Requirements

Hub configuration: CLI_API_TOKEN="base-token" (no colon)Client configuration: CLI_API_TOKEN="base-token:namespace"Mixing these up will cause authentication failures.

​
Token Format Reference

The namespace is specified using a colon separator: 
CLI_API_TOKEN:<namespace>
Valid examples:
  • secret-token-123:alice
  • my-team-token:dev
  • prod-token:staging-env
Invalid examples:
  • secret-token-123 (no namespace - will use default/no isolation)
  • secret-token-123:alice:extra (multiple colons not supported)
  • :alice (missing base token)

​
Security Considerations

Namespaces provide logical isolation, not cryptographic security. All namespaces share:
  • The same base authentication token
  • The same hub infrastructure
  • The same database
For true security isolation, run separate hub instances with different tokens.

​
Telegram Integration

When binding a Telegram account to a namespace:
  1. Open the Telegram Mini App from your bot
  2. Click the binding prompt
  3. Enter the full token with namespace: your-base-token:alice
  4. The Telegram account is now bound to the alice namespace
Each Telegram account can only be bound to one namespace at a time. To switch namespaces, unbind and rebind with a different namespace token.

​
Monitoring and Management

Namespaces are transparent to most HAPI operations: 
# List sessions (shows only your namespace)
hapi runner list

# Check runner status (namespace-scoped)
hapi runner status

# View diagnostics (shows your namespace configuration)
hapi doctor
The hub logs will show which namespace each operation belongs to for debugging purposes.

​
Migration Between Namespaces

There is no built-in migration tool for moving sessions or data between namespaces. If you need to switch namespaces, you’ll need to start fresh sessions.
To switch a machine to a different namespace:
  1. Stop all active sessions: hapi runner stop
  2. Clear credentials: hapi auth logout
  3. Update your token: export CLI_API_TOKEN="your-base-token:new-namespace"
  4. Re-authenticate: hapi auth login
  5. Start new sessions with the new namespace

Runner

Background runner for long-running sessions

Configuration

Environment variables and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us