Project configuration

volcano config deploy uploads a declarative manifest (volcano/volcano-config.yaml or ./volcano-config.yaml) to Volcano, which validates and applies the full project configuration:

• Project settings
• Database requirements
• Variables and function or frontend shared variable names
• Buckets and policies
• Realtime
• Notifications: where scheduler failure alerts go and when they are sent
• Auth configuration, including providers, email, templates, and managed pages: hosted pages for every page type, and the built-in pages' theme and layouts
• Function visibility, invocation mode, HTTP authentication, OpenAPI metadata, and schedulers
• Frontend custom domains, function routes, and Frontend routes
• Sandbox template image assertions and default session timeouts

The same manifest applies to local development and cloud projects — only the command namespace changes:

config pull downloads the target's current configuration as a canonical manifest rendered by Volcano; config deploy uploads a manifest and reconciles the target to match it. Both take the same flags (-f/--file, --force for pull, --dry-run for deploy) regardless of namespace.

version: 1
variables:
  - name: STRIPE_SECRET_KEY
    value: ${STRIPE_SECRET_KEY}  # interpolated from the CLI environment
realtime:
  enabled: true
notifications:
  email:
    enabled: true
    recipients: []             # the project owner; no other address yet
  webhook:
    url: https://example.com/hooks/volcano
  scheduler_failures:
    notify_on: consecutive_failures   # or first_failure
    threshold: 3
    notify_on_recovery: true
functions:
  - name: hello
    visibility: public         # private, authenticated, or public; omit to keep the current level
    variable_scope: scoped     # only the variables this function needs
    variables:
      - STRIPE_SECRET_KEY
    invocation_mode: http
    http_auth_mode: none
    openapi_spec:
      openapi: 3.1.0
      info: { title: Hello API, version: 1.0.0 }
      paths: {}
    schedulers:
      - name: refresh-cache      # required, unique per function (the reconcile key)
        cron: "*/5 * * * *"
        enabled: true
        payload: { job: refresh }
  - name: order-pipeline
    kind: durable              # standard or durable; asserted, not applied, since a kind is fixed at creation
frontends:
  - name: web
    function_routes:           # the complete set; routes left out are deleted
      - function: hello
        path_prefix: /api/hello
        strip_prefix: true
    frontend_routes:           # the complete set; routes left out are deleted
      - frontend: docs         # another frontend of the project
        path_prefix: /docs
  - name: docs

Cloud example — export the current cloud project's configuration to a file, edit it, and apply it back:

volcano login
volcano use my-project
volcano cloud config pull -f volcano-config.yaml   # export to file
$EDITOR volcano-config.yaml
volcano cloud config deploy -f volcano-config.yaml --dry-run   # preview
volcano cloud config deploy -f volcano-config.yaml             # apply

Key semantics:

• functions[].kind declares which entries are durable functions. It is asserted rather than applied, since a function's kind is fixed when it is created. It is also what tells the deploy commands apart: volcano functions deploy --all skips these entries and volcano cloud durable deploy --all deploys exactly them. Leave it out for a standard function, and leave the invocation settings out of a durable one — they describe synchronous HTTP invocation, which a durable function does not have.
• Declared config sections are the source of truth. Variables, bucket policies, OAuth providers, email templates, function schedulers, and frontend function and Frontend routes are fully synced when declared: entries absent from the manifest are deleted. Omitted sections and fields keep their existing values.
• Functions, frontends, databases, and buckets are never created or deleted through the manifest; only their configuration is updated. A manifest entry for a resource that does not exist is skipped with a warning. A deployed resource missing from a declared section is reported too. For a new frontend, run volcano cloud frontends deploy with the --variable-scope and --variable flags its entry needs, then volcano cloud config deploy (locally, volcano frontends deploy, then volcano config deploy). volcano deploy does this for you and applies the manifest after the code. A frontend created without them starts with no project variables.
• ${ENV_VAR} references are interpolated before upload. A reference to an unset variable is an error, and $$ produces a literal $.
• volcano config deploy --dry-run prints the projected actions without changing anything. Validation failures exit non-zero with Volcano's error list, and nothing is applied.
• If some entries fail to apply (a provider call failing mid-deploy), config deploy still prints a full report — succeeded entries included — and then exits non-zero because summary.errors > 0. Already-applied changes are not rolled back. Re-running config deploy with the same file is always safe: entries that already landed report unchanged, and only the entries that failed or still differ are retried.
• The notifications webhook signing secret is never part of the manifest. The first notifications.webhook.url a deploy sets generates one that is never shown. To get a secret you can use, run notifications rotate-webhook-secret. See notifications.md.
• A top-level lavaflow section is refused, naming its line, and nothing is sent. LavaFlow isn't part of the project configuration: delete the section, and turn LavaFlow on or off or change its settings with volcano cloud lavaflow. See lavaflow.md. If an older server exports the section, config pull removes it before writing the file.
• config pull leaves notifications.webhook out, because its URL can carry the receiver's token. A manifest without it keeps the saved webhook; set url: "" to remove it, or declare the URL through a ${ENV_VAR} reference.
• Variable values and write-only secrets, such as SMTP passwords, OAuth client secrets, and TLS material, are omitted from config pull exports. Keep them in your environment and set them via ${ENV_VAR} interpolation. If a server does return variable values, config pull removes the whole variables section before writing the file, so no values reach disk and the export stays deployable.
• functions[].variables is fully synced when declared: the list replaces the function's declared variable names. Omitting it, like omitting variable_scope, leaves the function's existing declaration untouched. See "Function variable scope" below.

Function visibility

functions[].visibility decides who can invoke a function:

• private: service keys and schedulers only.
• authenticated: also your project's signed-in users, including anonymous sign-ins.
• public: also anon keys with functions.invoke, and frontend function routes.

New functions start private, durable ones included. Leaving visibility out keeps the level the function already has. Any other value is refused before upload, naming the function.

A private function answers every caller but a service key or scheduler with the 404 of a function that does not exist. An anon key invoking an authenticated function by ID gets 403; by name, as the SDK invokes, 404. If your app gets 404 for a function you deployed, check its visibility with volcano cloud functions get <name>.

The deprecated public field still works, but public: false means authenticated, not private: it lets your signed-in users in. Manifests written by an older config pull contain it. To keep such a function private, replace it with visibility: private. true means public. config deploy and the function deploys print a warning for each public they read. When a function declares both, visibility wins, and the server rejects the pair only when exactly one of them says public, such as visibility: authenticated with public: true. config pull writes visibility only.

version: 1
functions:
  - name: notes-summary
    visibility: authenticated   # called by signed-in users from the dashboard
  - name: nightly-report
    visibility: private         # only schedulers and server-side code

Frontend function routes

frontends[].function_routes forwards every request under a path of a frontend to a function, so the browser calls it on the frontend's own origin:

version: 1
functions:
  - name: session
    visibility: public
    invocation_mode: http
frontends:
  - name: web
    function_routes:
      - function: session
        path_prefix: /api/session
        strip_prefix: true

The list is the frontend's complete set of routes:

• Omitting function_routes keeps the frontend's routes as they are.
• Declaring it replaces them: a route left out of the list is deleted.
• function_routes: [] deletes every route on the frontend.

A route reaches the function without a Volcano credential, so anyone who can load the frontend can call the function under its prefix. The function must authenticate its callers itself. A frontend can have up to 64 routes, and the longest matching prefix wins. config pull writes the routes back, so a pulled manifest deploys again unchanged.

One deploy can make a function public and add its route, or delete a route and make the function private. A route to a function that stays non-public fails the dry run and nothing is applied. See frontends.

Frontend routes

frontends[].frontend_routes serves every request under a path of a frontend from another frontend of the project, so one hostname runs several apps:

version: 1
frontends:
  - name: web
    frontend_routes:
      - frontend: docs
        path_prefix: /docs
      - frontend: docs
        path_prefix: /blog
  - name: docs

The list is the frontend's complete set of Frontend routes:

• Omitting frontend_routes keeps the frontend's Frontend routes as they are.
• Declaring it replaces them: a route left out of the list is deleted.
• frontend_routes: [] deletes every Frontend route on the frontend.

Function and Frontend routes on one frontend share one set of paths and the 64-route limit. A path listed in both is a validation error, as is a path the other kind already routes when the manifest leaves that kind alone. A deploy removes routes before it adds any, so it can move a path from one kind to the other. config pull writes frontend_routes after function_routes, only on frontends that have Frontend routes, so a pulled manifest deploys again unchanged. See frontends.

Frontend custom domains

frontends[].custom_domains lists every custom domain of a frontend. Each serves the frontend, or redirects to another listed domain that is active and serves it:

version: 1
frontends:
  - name: web
    custom_domains:
      - domain: www.example.com
        tls:
          mode: managed
      - domain: example.com
        tls:
          mode: managed
        redirect:
          to: www.example.com
          status: 308   # 301, 302, 307, or 308; default 308

• Omitting custom_domains keeps the frontend's domains as they are.
• Declaring it replaces them: a domain left out of the list is deleted, and the dry run names it.
• custom_domains: [] deletes every domain on the frontend.

A domain the deploy adds is not active yet, so add redirects to it in a later deploy. One deploy can add, remove, and retarget redirects among active domains, including swapping which domain serves. A frontend with one domain and no redirect can use custom_domain instead; an entry sets one or the other. config pull writes custom_domains when the frontend has more than one domain or any redirect. Until several domains per frontend reach your project, the list holds one domain. A server that predates custom_domains refuses the key in the dry run. See Custom domains and the configuration reference.

Frontend preview CORS

auth.cors.allow_frontend_previews: true lets the project's own live frontend previews call its auth and other endpoints from their origins, including with credentials. It applies only while CORS is enabled. Previews need no listing: each is allowed while it serves and refused once it is deleted or expires.

version: 1
auth:
  cors:
    enabled: true
    allow_frontend_previews: true

• Omitting allow_frontend_previews keeps the server's value.
• false turns it off.
• config pull writes it when it is on.

A server that predates the setting refuses the key in the dry run. See CORS configuration.

Shared variable names

Use shared_variables to select the complete list of existing project variables shared with functions, without changing their values:

version: 1
shared_variables:
  - LOG_LEVEL
  - SERVICE_URL

Names are case-sensitive, must be unique, and must already exist. Each name must start with a letter or underscore and contain only letters, digits, or underscores. Supply names only, not objects containing values.

Omitting shared_variables leaves membership unchanged. Declaring shared_variables: [] clears the shared list. Names left out of a declared list remain stored as non-shared variables; this does not delete their values. The separate variables section still has its own full-sync semantics.

A variable entry can set its own shared instead:

version: 1
variables:
  - name: STRIPE_SECRET_KEY
    value: ${STRIPE_SECRET_KEY}
    shared: false   # only scoped functions that select it receive it
  - name: LOG_LEVEL
    value: info     # no shared: a new variable is shared, an existing one keeps its setting

Omitting shared keeps today's default: a new variable is shared and an existing one keeps its setting. When the manifest also declares shared_variables, that list decides membership for every variable and an entry's own shared is ignored, so use one or the other. variables deploy --shared=false sets the same field for the variables in an env file.

config pull exports shared names only and omits variable values, so a variable saved as not shared is absent from the exported list. The exported list can be deployed back to the same project without supplying those values. Use config deploy --dry-run to preview a membership change.

Frontend variable scope

Use frontend_shared_variables to select the complete list of existing project variables shared with frontends:

version: 1
frontend_shared_variables:
  - NEXT_PUBLIC_VOLCANO_API_URL
  - NEXT_PUBLIC_VOLCANO_ANON_KEY
frontends:
  - name: web
    variable_scope: shared

Declaring frontend_shared_variables replaces the complete frontend shared list. Omitting it preserves the current membership, and declaring frontend_shared_variables: [] clears the list. Each name must already exist as a project variable.

For a frontend, variable_scope accepts:

• all to use all project variables.
• shared to use frontend_shared_variables.
• scoped to use the names in that frontend's variables list.

Hosting rejects a frontend environment over 4,096 bytes before changing state. NEXT_PUBLIC_* variables are build-only. Rebuild each frontend when changed values must be embedded in browser assets.

Run volcano config pull before editing the manifest. It writes each frontend's domains into its entry, so deploying the file back keeps them on any server. An entry that leaves out custom_domain and custom_domains also keeps its domains, except on a server that predates this; see deploy.

Function variable scope

By default a function receives every shared project variable, which is every variable unless some were saved as not shared. Set variable_scope to scoped to give it only the variables it actually needs:

version: 1
variables:
  - name: STRIPE_SECRET_KEY
    value: ${STRIPE_SECRET_KEY}
  - name: SENDGRID_API_KEY
    value: ${SENDGRID_API_KEY}
functions:
  - name: charge
    variable_scope: scoped
    variables:
      - STRIPE_SECRET_KEY
  - name: notify
    variable_scope: scoped     # SENDGRID_API_KEY is read directly, so detection finds it

Because functions deploy reads these declarations from the manifest, every ${VAR} reference in the file must be set in the deploying shell. If one is not, the deploy stops before uploading rather than continuing without the scope declared here. See functions.

variable_scope takes all or scoped:

• all is the default and gives the function every shared project variable (see Shared variable names).
• scoped gives it the names listed in variables, plus the names Volcano detects in the function's source that the project defines.

Volcano reads the uploaded source and adds direct environment references it finds there, so a variable the function reads by its literal name does not need to be listed. List a name in variables when:

• the function reads it through a computed key, which detection cannot see, or
• the function must not deploy without it.

That difference matters on apply. A name you declare that the project does not define fails the deploy; a name Volcano merely detected that the project does not define is ignored, since such a reference is often optional.

A scoped function whose resulting environment exceeds 4096 bytes is rejected before anything is deployed.

Both fields are optional and independent of each other. Omitting them sends nothing, so an existing function keeps whatever scope it already has, and a manifest written before scoping existed behaves exactly as it did.

Coming from Terraform?

There is no state file (.tfstate or equivalent) behind volcano-config.yaml. Every config deploy — including --dry-run — asks Volcano to diff the manifest against the project's actual live configuration, not a cached snapshot of a prior apply. Practical implications:

• No import / state rm / state mv: point the manifest at an existing project and run config deploy; there's nothing to reconcile into a state file first.
• No separate drift-detection step: there's no stored copy to go stale — every plan reads live configuration directly, so any actual drift just shows up as the next diff and gets reconciled.
• --dry-run is a live report, not a saved plan artifact — you can't inspect it later or hand it to a later config deploy; running config deploy always recomputes the plan from scratch.
• No workspaces, no -target: the whole manifest reconciles against the currently selected project (volcano use, the directory's link, or the deprecated VOLCANO_PROJECT_ID) as one unit. Omitting an entire section or field leaves it untouched. That does not apply within a section you've already declared as fully synced (variables, buckets[].policies, auth.providers.oauth, auth.email.templates, functions[].schedulers, functions[].variables, frontends[].function_routes, frontends[].frontend_routes) — omitting one entry from an otherwise-declared list still deletes that entry, since the declared list is the source of truth for the whole section. See "Key semantics" above.
• A failed deploy doesn't need an explicit resume step — see the apply-phase failure bullet above; re-running the same manifest picks up only what's still outstanding.

See the server-side configuration manifest reference for the full reconciliation semantics.

Behavior changes from older CLI releases:

• Buckets are no longer auto-created.
• An omitted policies key now leaves a bucket's policies untouched; older releases deleted them all.
• Schedulers are now deleted by omission within a declared schedulers list.
• The scheduler regions field is no longer supported. Placement is managed by Volcano.

Frontend variable scope

An existing frontend can select exactly which project variables its build and runtime receive:

version: 1
frontends:
  - name: web
    variable_scope: scoped
    variables:
      - NEXT_PUBLIC_API_URL
      - SESSION_SECRET

Apply with volcano config deploy (local) or volcano cloud config deploy. The server must support frontend variable scopes. Missing declared variables reject apply. Omitting a field preserves it; variables: [] clears the selection. all keeps the legacy frontend behavior of reading all project variables, not just the function shared list. NEXT_PUBLIC_* variables are used during build and excluded from runtime. Rebuild the frontend to change values embedded in browser assets.

Sandbox template settings

Declare an existing template by name. memory_mb and ports assert the deployed image settings; changing them requires a new source deployment. Configuration apply updates ttl_seconds, the default VM lifetime for new sessions.

version: 1
sandboxes:
  - name: local-custom
    memory_mb: 1024
    ports: [8080]
    ttl_seconds: 600

Preview with volcano config deploy --dry-run, apply with volcano config deploy, and export with volcano config pull --force. Add cloud after volcano for a cloud project. Omitted fields preserve current settings. Cloud TTL must be 30–28800 seconds. Local mode accepts 0 for unlimited lifetime or a positive TTL. idle_timeout_seconds is no longer supported; remove it from existing manifests. Config apply does not build images or delete templates omitted from the manifest. See Sandbox source deployment.