Platform configuration

• Public URL — the address people and agents use to reach OvalBee. Email links, sign-in callbacks and the MCP address shown to agents are built from it. Set it first.
• Public flows workspace — the only workspace whose flows can be published as read-only public examples. Empty means publishing is off.
• Official library URL — the OvalBee instance that official templates come from. It points at app.ovalbee.com by default. Templates saved on this installation don’t depend on it.
• Request tracing — diagnostic tracing, the threshold for logging slow database queries, and how long recorded traces are kept (7 days by default, whether tracing is on or off).

All user accounts on the installation, with their sign-in provider, instance role and last sign-in. Create accounts, edit them, set passwords, and deactivate or reactivate users. See Sign-in and accounts.

• Flow agent — the OpenAI and Anthropic API keys and the one model that AI Chat and the nodes calling a language model, such as Dataset insights, run on for every workspace. Without a key for the model’s provider, AI Chat is off and those nodes fail. Agents connected over MCP use their own model and don’t need this.
• Product analytics — PostHog settings.

SMTP host, port, security, credentials and the sender address. Leave the host empty to turn email off. Invitations and password resets need it.

Token lifetimes, secure cookies, the signup form, external sign-in providers (OpenID Connect, Google, GitHub) and bot protection. See Sign-in and accounts.

Whether node runs start as Docker containers or Kubernetes pods, and the backend’s options, including the requestMappings that machine classes point to. On a self-hosted installation, Kubernetes needs the Business plan. See Compute.

The machines people choose between when they run a node or start a deployment: their order, names, device types and the request mapping each uses. See Compute.

Where files are kept. Providers describe the storage backends — S3-compatible storage (AWS S3, MinIO, Ceph and similar), Azure Blob Storage, Google Cloud Storage, or a folder on the server’s disk — and Workspace storage picks the one workspaces use. Bucket routing connects data that lives outside the main storage. Each row maps a virtual bucket to a physical bucket on a provider. The virtual name is the one assets (s3://<virtual bucket>/...), URLs and S3 clients use, and the form shows it as fixed once saved: renaming a virtual bucket would orphan every asset that refers to it. The physical bucket and the provider can be edited at any time, so after you copy a bucket’s data to another bucket or provider, point its row at the new home and nothing that refers to the virtual name needs to change. S3 clients only ever see the virtual name. A virtual name can’t be the workspace bucket name or the name of the workspace storage bucket, and a route can’t point at the workspace storage bucket itself. Deleting a row stops every asset that references its virtual name from resolving. Only the form protects the virtual name; the configuration file and the settings API accept removing a row and adding another, so treat a virtual name as permanent. A physical bucket name is whatever the provider accepts, for example Google Cloud Storage names with underscores.

A cloud provider’s Authentication setting chooses how OvalBee signs in; the form shows only the fields of the chosen method.

• Amazon S3 / S3-compatible: access keys (a static key pair; use an IAM role for temporary credentials); an IAM role from the API server’s own AWS credentials (environment, IRSA, ECS task role or instance profile), optionally assuming another role; or IAM Roles Anywhere, which exchanges an X.509 certificate and private key for temporary credentials.
• Azure Blob Storage: account key, SAS token, connection string, or Microsoft Entra ID with a client secret, a client certificate, a managed identity or an AKS workload identity. The endpoint is optional and defaults to https://<account>.blob.core.windows.net. Aborted multipart uploads leave uncommitted blocks, which Azure discards after about a week.
• Google Cloud Storage: a service account key (the JSON key file) or Application Default Credentials, which cover GKE workload identity, the Compute Engine metadata server and GOOGLE_APPLICATION_CREDENTIALS. Credentials are sent only to *.googleapis.com endpoints; a custom endpoint is meant for emulators and proxies that need no authentication. Large uploads use Cloud Storage’s multipart uploads, whose parts stay billed until the upload completes, so add a lifecycle rule that deletes incomplete multipart uploads (for example after a day).

Secrets such as keys, tokens and private keys are stored encrypted and shown as ******; leave a field empty to keep its stored value. For Google Cloud Storage through its S3 interoperability API, add an S3 provider with the endpoint https://storage.googleapis.com and HMAC keys instead.

A Filesystem provider is meant for a single-machine install whose data already sits on local disk, so it is used in place without copying. With Docker Compose, mount the host folder into the API container at /mnt/ovalbee-storage (for example - /srv/ovalbee-data:/mnt/ovalbee-storage under the api service’s volumes), then enter the Folder below that mount. Each bucket is a folder inside the provider’s folder, and each object a file. The provider’s folder must sit on one filesystem. Symbolic links to files or folders inside the provider’s folder are followed when reading and listing; links that lead outside it are ignored, and writes never go through a symbolic link. Objects keep no metadata: the content type is taken from the file extension, and custom metadata and cache headers sent with an upload are not stored. Parts of uploads in progress are kept in hidden .ovalbee-tmp and .ovalbee-multipart folders inside the provider’s folder and removed after a day if the upload is abandoned.

In the configuration file, a bucket route sits under objectStorage.buckets, keyed by its virtual name:

objectStorage:
  buckets:
    photos:
      bucket: acme-photos-eu
      provider: archive
      access: read
    shared:
      bucket: acme-shared
      provider: archive
      access: readwrite
      paths:
        - uploads/
        - exports/2026/

Here s3://photos/... resolves to the bucket acme-photos-eu on the provider named archive, which must be defined under providers.

Two optional restrictions apply to a whole route, and OvalBee enforces both itself: a request outside them is refused with AccessDenied and never reaches the provider. Access is read or readwrite; a read-only route refuses uploads, deletes and multipart uploads, which protects the data from accidental writes. A route that omits access is read-only, so add access: readwrite to a route in the configuration file to keep writing to it; routes saved in the admin before this setting existed keep read and write. Paths limit the route to some folders of the physical bucket (enter one per line, as in the example above), for credentials that may only reach part of it; leave them empty for the whole bucket. A path is a folder name such as exports/2026/, without . or .. parts, and no path may sit inside another. Keys keep the names the client gives them, with no prefix added. Listing a folder above the allowed ones shows only the allowed folders, so a client can browse down to them, and a listing without a delimiter returns only the keys under them. Listing a prefix that reaches none of the allowed folders is refused like any other request outside them.

On a self-hosted installation, storage providers besides the workspace one, and any bucket route, need a plan that includes storage buckets: Business does, Community does not. Without one, Add provider and Add bucket are shown locked, and those added earlier — in the UI or in the configuration file — stay listed but aren’t used: requests to a routed bucket are refused until the plan includes them again. Ones added in the UI can still be removed there. Routed buckets are offered to every workspace.

Workspaces can also connect buckets of their own under Settings → Storage, with credentials of their own. Those never use the server’s identity: the IAM role from the default credential chain, an Azure managed or workload identity, Application Default Credentials and the filesystem provider are left out, and OvalBee refuses to connect a workspace’s provider to a private, loopback or link-local address. A workspace bucket works like a route: a virtual name that never changes, a physical bucket and provider that can be repointed, and the same Access and Paths, enforced the same way. A workspace cannot name a bucket after a route, and the admin cannot add a route under a name a workspace’s bucket already has. A route added in the configuration file is not checked: if a workspace already has a bucket under its name, that workspace keeps using its own bucket and does not reach the route, and the API logs a warning.

Storage cleanup sets how long data can go unused before it is moved to the trash, how long the trash keeps it, and how long data that left the trash keeps its rows and files so support can still bring it back before they are erased. See When data is deleted. It also sets how long log lines of runs and deployments are kept (90 days by default) and how long a deleted AI chat stays in the database before it is erased (30 days by default). Each period is checked every night, and 0 means no wait: the next night removes everything it covers.

Qdrant embedding index limits the shared index behind AI search, similar pairs and the other embedding nodes: how much vector data and metadata one workspace may store per embedding model, and the disk usage above which every workspace stops writing. A changed limit reaches an existing index the next time a node uses it.

On self-hosted installations, the installation’s plan and license. A license file you received from OvalBee is applied with ovalbee license apply. On OvalBee Cloud, billing is per workspace instead, under Settings → Billing.