Skip to content
Watasu Docs

Core Concepts

You can do a lot on Watasu with a small vocabulary. Once you have the mental model, the CLI, dashboard, and API map cleanly onto it.

App

Section titled “App”

An app is the deployable unit. It owns its source, builds, releases, configuration, processes, attached add-ons, and domains.

Apps live inside a team and have a stable name (billing-api, dashboard). They get a managed *.watasuhost.com URL the moment you create them.

Build

Section titled “Build”

A build turns your source code into a runnable container image.

Watasu picks the build system from your repo:

  • if a Dockerfile is present, Watasu builds it
  • otherwise, Watasu uses Cloud Native Buildpacks to detect your stack

Builds are triggered by git push watasu main, by GitHub auto-deploy, by pipeline dispatch, or by promoting an existing image between stages.

Release

Section titled “Release”

A release is an immutable snapshot of “what’s live”: a specific image, a specific process formation, a specific set of config vars, and a specific set of attached add-ons.

Every deploy creates a new release. Every config var change creates a new release. That’s why “what changed” is always answerable on Watasu — releases are the unit you point at.

Process

Section titled “Process”

A process is one named workload inside an app. The name decides how Watasu routes traffic to it:

  • web and any name ending in -web (like admin-web, api-web) are exposed publicly with HTTP and TLS
  • any name ending in -tcp (like grpc-tcp) is a private TCP service reachable only by other apps your team explicitly trusts
  • any name ending in -rtc (like sfu-rtc) gets a dedicated TURN gateway, a public UDP port, and per-replica hostnames — for WebRTC, SFUs, and voice agents
  • a process named release runs once per deploy, before the new release goes live (migrations, one-time setup); a name ending in -release (like admin-release) does the same but only gates the processes sharing its prefix
  • everything else (like worker) runs but isn’t reachable from the network

You can have multiple *-web processes in one app — each gets its own URL and can have its own custom domain. You declare all processes in a Procfile, or rely on the inferred default web process if you don’t have one.

Formation

Section titled “Formation”

The formation is the shape of your app at runtime: which processes exist, how many replicas of each, and what pod size each replica gets.

Pod sizes range from hobby up to standard-16x. You scale the formation independently per process — web=3 worker=1, each at its own size. See Pod Sizes for the full catalog.

Add-on

Section titled “Add-on”

An add-on is a managed service attached to an app. PostgreSQL, Valkey, ClickHouse, Redpanda, object storage, and the monitoring stack (logs, metrics, traces, Grafana) are all add-ons.

Add-ons are owned by the team and attached to apps. That separation means:

  • the same database can be attached to multiple apps with aliases
  • restoring or promoting a database doesn’t replace your app
  • backups, restores, and promotions are first-class operations

When you attach an add-on, Watasu injects its connection details as config vars (DATABASE_URL, REDIS_URL, S3 credentials, and so on). Your app picks them up on the next release.

Sandbox

Section titled “Sandbox”

A sandbox is an isolated Linux environment for agent work and automation. It is created from a template version with explicit CPU, memory, and TTL settings, and can run commands, read and write files, expose explicit HTTP preview ports, and create disk checkpoints.

Sandboxes are not app releases. Use them for temporary workspaces and code execution; use apps for long-running services and production workloads. See Sandboxes Overview.

Team

Section titled “Team”

A team is the ownership boundary for apps, add-ons, and sandboxes. Team membership controls who can see, deploy, operate, and manage them.

Most users only need to know: invite people to a team, and apps, add-ons, and sandboxes created in that team are reachable to those members at the access level you grant.

How it fits together

Section titled “How it fits together”

The day-to-day loop:

  1. you push code → Watasu builds an image
  2. the image plus the current config and formation become a new release
  3. the release is rolled out across your processes
  4. add-ons keep humming along between releases
  5. sandboxes handle temporary agent workspaces and code execution
  6. logs, metrics, and traces stream into Grafana while it runs

Once that loop is intuitive, every other page on this site is just detail.