DOCSEARCHbyAlgolia
Submit Docs

Velane Documentation

website·Indexed 31 days ago

https://docs.velane.sh

Cloud infrastructure for deploying agents, APIs, and small software. Features include a control-plane with separate execution runtimes, multi-tenant isolation, a KV store for persisting JSON values, and first-class MCP server support for coding agents. Supports sync, async, and stream invocation modes for snippets, with pre-installed executors for Mastra (Bun) and LangGraph (Python).

Tokens
10.9K
Snippets
37
Records
112
Agent score
60%

What's inside Velane

  1. Overview of Velane cloud infrastructure

    Velane is a cloud infrastructure platform used for deploying agents, APIs, and small software. It allows developers to build and manage production services using AI tools (Claude, Codex, Cursor) or via its API, CLI, and admin portal. Key capabilities include:

    • Versioning and deploying code across dev, staging, and prod environments.
    • Managing secrets and runtime limits for secure sandboxed execution.
    • Invoking code using sync, async, or streaming modes.
    • Connecting to over 800 OAuth integrations without managing provider tokens in the snippet code.
    • Operating multi-tenant workloads with scopes, tenancy boundaries, and compliance controls.
    • Building agent-native workflows with native Model Context Protocol (MCP) support.

  2. Understand Velane's core architectural components

    Velane utilizes a control-plane architecture with separate execution runtimes. The system consists of the following components:

    • control-plane: Handles API, authentication, scheduling, and tenancy.
    • bun executor runtime: Execution environment for Bun-based tasks.
    • python executor runtime: Execution environment for Python-based tasks.
    • postgres: Primary database.
    • redis: Caching and messaging.
    • mcp server: Model Context Protocol server.
    • admin portal: Administrative interface.
    • embed dashboard: Embedded user interface.
    • nango: Internal integration management.

  3. Understand the Velane snippet invocation lifecycle

    When a snippet is invoked via a Client or MCP (Model Context Protocol), the request follows a specific architectural flow to ensure security, tenancy, and isolated execution:

    1. Entry: The request hits the Control-plane API.
    2. Validation: The system performs Authentication, tenant verification, and scope checks.
    3. Resolution: The Scheduler determines the correct snippet version and target environment.
    4. Dispatch: The request is dispatched to either a Bun or Python executor.
    5. Execution: The snippet runs within the executor with necessary libraries and context injected.
    6. Response: The result is returned to the caller based on the configured mode (sync, async, or stream).
    flowchart LR
  A[Client or MCP invoke] --> B[Control-plane API]
  B --> C[Auth + tenant + scope checks]
  C --> D[Scheduler resolves snippet version and environment]
  D --> E[Dispatch to Bun or Python executor]
  E --> F[Snippet runs with injected context and libraries]
  F --> G[Result returned sync, async, or stream]

  4. Understand the Velane integrations architecture

    Velane integrations allow snippet code to call provider APIs without handling OAuth tokens directly. The system centralizes OAuth lifecycle handling and keeps credentials out of the snippet code by proxying requests through an internal integration path. The workflow is: 1. Configure/connect a provider in the admin portal; 2. Velane stores connection metadata for the tenant; 3. Snippets call the built-in integrations client; 4. Velane proxies the request to the provider.

  5. Implement the Queued-Streaming Sync Architecture

    The target architecture decouples the API (control-plane) from the execution (worker) using Redis. All invocations are enqueued as jobs; a separate worker process executes the code and publishes typed events to a per-invocation Redis Stream. The API handler reads these events and relays them to the client via SSE or as a final JSON response.
    client ──(SSE or JSON)──► control-plane: InvocationsHandler
        │ 1. resolve snippet/version/env, create invocation (pending)
        │ 2. open Redis Stream reader at "$" for inv:<id>:events
        │ 3. enqueue job on velane:jobs
        ▼
      Redis (jobs list + per-invocation event stream)
        ▲ BRPOP
        │
     worker (separate replica)
        │ status→running
        │ RunStream(spec) → executor runtime (Bun/Python)
        │ for each typed event: XADD inv:<id>:events
        │ env != dev → drop "log" events
        │ on finish: XADD {result}/{error} + {done}; finalize DB row
        ▼
handler XREADs events:
   - SSE caller: forward each as an SSE event; close on {done}
   - JSON caller: accumulate; on {done} return final JSON body

  6. Use the KV store for persisting state between invocations

    The KV store allows you to persist small JSON values across snippet invocations. It is ideal for incremental-sync cursors, deduplication markers, and simple workflow memory. It is not a cache, blob storage, or secret store; use object storage for large/binary data and Variables/Credentials for secrets. Values are stored as plaintext JSONB and are not encrypted.

  7. Understand the Velane request authentication and authorization flow

    Before Velane executes work, every client request undergoes a three-step validation process to ensure safe multi-tenant behavior:

    1. Authentication (Who is calling?): The system validates the credential type. Supported credentials include Session JWTs, API keys (starting with vl_*), and Embed tokens (starting with et_*).
    2. Tenant Context Resolution (Where can they do it?): The system determines the specific tenant environment associated with the request.
    3. Scope Check (What can they do?): The system verifies if the request has the required permissions (e.g., invoke, manage, or admin).

    Once these checks pass, the request is passed to the handler logic for execution.

    flowchart TD
  A[Client request] --> B{Credential type}
  B -->|Session JWT| C[Session validation]
  B -->|API key vl_*| D[API key validation]
  B -->|Embed token et_*| E[Embed token validation]
  C --> F[Tenant context resolution]
  D --> F
  E --> F
  F --> G[Scope check invoke/manage/admin]
  G --> H[Handler logic]
  H --> I[Response]

  8. Understand the Velane monorepo structure

    Velane is organized as a monorepo containing services, applications, and shared libraries. The primary directories are:

    • services/control-plane: Go API server and scheduler.
    • services/executor-runtime: Bun and Python execution runtimes.
    • services/mcp-server: MCP integration server.
    • services/cli: Command-line interface.
    • apps/admin: Main dashboard.
    • apps/embed-dashboard: Read-only embeddable dashboard.
    • platform-libraries: Built-in libraries for snippet runtimes, including @velane/integrations / velane.integrations and @velane/store / velane.store.

  9. Understand tenant isolation in Velane Authenticated APIs

    Velane is multi-tenant by design. Isolation is enforced via tenant predicates on every public tenant-scoped query, ensuring that one tenant cannot read or mutate another tenant's resources. This isolation applies to all public tenant-scoped APIs, including snippet invocation and management, which are bound to tenant ownership.

  10. Configure host requirements for Firecracker mode

    To use Firecracker mode in Velane, the host machine must have KVM (Kernel-based Virtual Machine) support enabled and requires additional setup beyond the standard installation.

  11. Maintain Velane documentation

    Documentation ownership is split between service-specific and shared content:

    • Service-specific docs: Maintained by the respective service owners within their service directory.
    • Shared behavior: Documentation for cross-cutting concerns such as authentication, invocation, and integrations is located in the top-level docs/ directory.

  12. Choose between Stream mode and Invoke mode

    Use stream mode when you expect progressive output. For standard request-response handlers, use the regular invoke mode for simplicity.