Nebula Deck Documentation

Recovery key

When the vault is initialised, your deck shows a one-time recovery key. Save it somewhere safe — a password manager, a sealed envelope, anywhere offline. It's the only way to unlock the vault if you lose access to both your passkey and password. The deck will not show it again.

Comparison

Add a key

1. Settings → LLM Providers. Pick the provider card you want to enable.
2. Paste the key. It's encrypted at rest in your deck's vault and redacted from every log surface.
3. Choose a default model (optional). Otherwise the deck picks the recommended model for that provider.
4. Set fallbacks (optional). If a provider rate-limits or fails, the deck rolls to the next one in your chain.

All five are editable from Settings → Identity. Changing the agent name or emoji updates everywhere instantly — including across connected channels.

Connect a channel

1. Settings → Channels → Add. Pick the platform you want to wire up.
2. Paste credentials from the platform's developer portal. Each card has step-by-step instructions for that platform.
3. Set access policy — who can DM, which groups the bot answers in, whether it responds on every message or only when @mentioned.
4. Save. The deck connects in the background. Status flips to connected when it's live.

Access control

Three knobs control who can talk to your bot. Defaults are conservative — DMs require an allowlist, groups require an @mention.

Self-approval (OTP)

Telegram, Discord, Matrix and WhatsApp support OTP self-approval. A user not on your allowlist who DMs the bot gets a one-time code prompt; the code shows up in Channels → Senders in your deck. Approve and they're added — three failed attempts trigger a five-minute cooldown.

What will be importable

Each category will be a checkbox — pick what you want, leave the rest. Categories that aren't available in your export will be greyed out automatically.

If you have multiple agents in your source install, non-default ones come over as separate personas on your deck — same provider keys, different identity.

What runs inside the deck

Shell commands execute directly inside your deck's sandboxed container. The container itself is the sandbox — restricted syscalls, capped resources, isolated networking. No Docker-in-Docker, no nested VMs.

When to use the deck vs a worker

Add a server

1. Settings → MCP Servers → Add.
2. Pick a transport. Remote HTTP for hosted MCP servers (Linear, Atlassian, custom). stdio for npm-package servers your deck spawns as a child process.
3. Paste the URL or command. Headers and arguments are accepted; secrets are stored encrypted and redacted from every status view.
4. Save. Tools appear alongside built-ins within seconds.

For remote servers, secrets in URLs and headers can reference ${ENV_NAME} placeholders that resolve from Settings → Environment Variables on your deck. The UI only ever shows back a sanitized URL plus header names — never raw values.

OAuth-protected servers

If a remote MCP server requires OAuth 2.1, the deck handles it transparently. On the first 401, it discovers the auth server, registers a client, and pops a browser window for you to log in. Tokens are cached — you only authenticate once per server. If a session expires later, the deck re-authenticates automatically on the next 401.

Lifecycle

1. Boot. The deck launches the server (stdio) or opens a connection (remote).
2. Initialize. Capabilities are exchanged; tools become available to the agent.
3. Run. Tool calls flow on demand. Heartbeats keep the link alive.
4. Recover. A crash triggers a restart with exponential backoff. After repeated failures the server is parked and re-enabled later.

If your provider key already covers TTS or STT (e.g. an OpenAI key), the deck auto-detects it — no extra setup required.

Auto-speak modes

Personas

A persona is a named, reusable voice identity. It bundles a provider-neutral prompt — profile, style, accent, pacing — with per-provider bindings (voice id, model, stability). One active persona at a time, applied to every TTS call automatically.

{
  "id":    "alfred",
  "label": "Alfred",
  "prompt": {
    "profile": "A wise British butler with dry wit",
    "style":   "Measured, deliberate, slightly amused",
    "accent":  "Received Pronunciation",
    "pacing":  "Unhurried, with dramatic pauses"
  },
  "providerBindings": [
    { "provider": "openai",    "voice_id": "cedar", "model": "gpt-4o-mini-tts" },
    { "provider": "elevenlabs", "voice_id": "21m00Tcm4TlvDq8ikWAM", "stability": 0.65 }
  ]
}

Providers that accept free-form instructions (OpenAI gpt-4o-mini-tts, Gemini TTS) get the full prompt. ElevenLabs and Google Cloud apply only the binding overrides.

Connect an account

1. Settings → Calendars → Add account.
2. Pick the provider. Fastmail and iCloud only need a username and an app-specific password — never your main account password.
3. Generic CalDAV? Paste the base URL (e.g. https://cloud.example.com/remote.php/dav) along with credentials.
4. Save. Multiple accounts are fine — pick one as the default, the agent will ask which to use otherwise.

Operations

Updates and deletes use ETag-based optimistic concurrency. If you edited the event from your phone since the agent last fetched it, the server rejects the write — the agent re-reads and retries instead of clobbering your change.

Example

Why workers exist

Your deck runs in a 512MB container with 10GB storage. That's plenty for everyday work — chat, coding, scripting, automations. But some tasks need more:

Worker types

All workers are billed per second with a 60-second minimum. The meter stops the moment the container shuts down.

Spawning a worker

Workers are always explicit — your deck never spawns one on its own. Two ways to trigger:

During a run

Events stream back to your chat in real time — you can see what the worker is doing, ask it questions, or tell it to change direction. If the worker gets stuck, it asks you and waits. You're never locked out.

Compute tiers

Workers require a compute tier subscription. Each tier bundles a monthly credit and a concurrency limit:

Each tier includes the $7 deck. If you exceed your credit, compute keeps running at the same rate — overage appears on your next bill. Set a hard spending cap in your dashboard if you want one.

When a task needs JavaScript rendering or page interaction, your deck provisions an isolated browser session on demand. Chrome boots in its own container, connects via CDP, and is reaped when idle. Nothing to install, nothing running when you're not using it.

What the agent can do

Element references

Snapshots return numbered refs instead of CSS selectors. References survive minor markup changes, never expose fragile path strings to the model, and identify elements by role + content rather than DOM position.

{
  "ref_":        1,
  "tag":         "button",
  "role":        "button",
  "text":        "Submit",
  "aria_label":  "Submit form",
  "visible":     true,
  "interactive": true,
  "bounds":      { "x": 100, "y": 200, "w": 80, "h": 40 }
}

Browser vs. fetch

Domain restrictions

Want to keep the agent on a leash? Settings → Browser → Allowed domains lets you whitelist sites the browser can navigate to. Wildcards work — *.github.com matches all subdomains. Anything outside the list is rejected before a request goes out.

What's hardened by default

Your deck and its compute containers (browser sessions, coding agents) are secured with multiple layers of isolation:

Secrets handling

• Encryption at rest vault-backed key storage
• Zeroed on drop no lingering plaintext in memory
• Redacted in logs debug output never leaks values
• Sanitized in UI remote URLs and headers display masked

Need a custom isolation policy or VPC peering for your deck? Talk to us — that's exactly what the higher tiers are for.