Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tesslate.com/llms.txt

Use this file to discover all available pages before exploring further.

Tesslate OpenSail

​
What a project is

A project on OpenSail is a self-contained working environment. It holds your source code, the containers that run it, a persistent volume that survives restarts, per-project permissions, and a typed graph of how everything connects. Every project carries:
  • A slug like my-app-k3x8n2 that identifies it in URLs, logs, and the file system
  • A runtime (local, docker, or k8s) picked per project, not per workspace
  • A visibility flag (team or private) that governs who can open it
  • A volume that persists files across compute shutdowns
  • A .tesslate/config.json graph describing apps, infrastructure, connections, previews, and deploy targets
  • A chat history with every agent step ever run against it

Source code

Your files, tracked and editable from Monaco, agents, and the terminal simultaneously.

Containers

One or more services (frontend, backend, database) wired together in a shared network.

Persistent volume

btrfs-backed storage on Kubernetes, filesystem on Docker, host folder on desktop local.

Graph config

.tesslate/config.json is the source of truth for the Architecture Panel.

​
Anatomy of a project

A project has four pieces. All four are agent-readable and agent-writable.
On Docker: /projects/{user-id}/{project-id}. On Kubernetes: the mounted btrfs subvolume in proj-{uuid}. On desktop: $OPENSAIL_HOME/projects/{slug}-{uuid} or a symlinked folder you adopted. The agent, the terminal, and the editor all see exactly this tree.
Every container is a row in the Container table and a node on the Architecture Panel. Each has a name, image, port, env vars, a startup command, and a role (base, service, external, hybrid). Containers in the same project share a network and can reach each other by DNS.
A project-scoped permission policy gates tool calls. Shell, network, git push, file writes, and process spawning each have an allow, deny, or ask policy. On desktop these live in .tesslate/permissions.json. On the cloud they combine with team RBAC (admin, editor, viewer) and project memberships.
The canonical graph. Apps, infrastructure, connections, deployment targets, previews, and canvas positions all live here. The Librarian agent writes this during setup. Humans edit it on the Architecture Panel. Agents edit it with the apply_setup_config tool. Never edit this file through write_file. Always round-trip through the schema so Container records stay in sync.

​
Runtime per project

Every project picks its own runtime. The same desktop app can run one project locally with no containers while another runs in your production Kubernetes cluster.
Subprocesses on the host machine. No Docker, no cluster, fastest cold start. Good for single-service prototypes and scripts. Uses services/orchestration/local.py.
The runtime is a column on the Project model. get_orchestrator(project=project) dispatches to the right backend. You can switch runtimes, but it requires a restart and may involve a file sync.

​
Three-tier compute

Kubernetes projects live on a tiered model so idle workspaces cost almost nothing.
TierWhat runs hereCost profile
Tier 0File reads, web fetches, agent reasoning, most tool callsNear zero, no compute pod
Tier 1Shell commands via a warm ephemeral poolInstant execute, returns to pool
Tier 2Full project namespace with live preview and long-running dev serversOn-demand, hibernates when idle
About 99 percent of agent operations stay in tiers 0 and 1. Tier 2 starts when you click Start or open a preview, and it hibernates (volume-level) after a configurable idle window.

​
Visibility and access

Projects are either team (inherits team RBAC) or private (owner-only). A team admin sees every team-visible project. A team editor can edit them. A team viewer can open them. Project-level overrides (ProjectMembership) let you grant or tighten access per user. Every significant action writes to an append-only audit log keyed by team and project.

​
Lifecycle

1

Create

POST /api/projects creates the row, allocates a slug, and runs _perform_project_setup in the background. Setup clones the template or git repo, writes files to the volume, and syncs .tesslate/config.json.
2

Configure

The Librarian agent inspects the tree and writes .tesslate/config.json. You can also hand-edit on the Architecture Panel or during the setup wizard.
3

Start

POST /api/projects/{slug}/start boots containers. On Kubernetes, it ensures the namespace, PVC, and file-manager pod, then creates Deployments, Services, and Ingress rules.
4

Build

Agents and humans edit files, run commands, and iterate. The preview hot-reloads. Steps persist progressively.
5

Hibernate

After the idle window, the whole volume is snapshotted and compute torn down. Files are intact.
6

Restore

Open the project and compute resumes from the snapshot. Same files, same containers.

​
How agents see a project

The agent receives a structured context on every run: project info, git status, the current .tesslate/config.json, open chat history, attached skills, and a live file tree. It writes through the same file API you use, so its edits and yours converge on the same checkout. When it changes infrastructure, it calls apply_setup_config, which validates startup commands, upserts Container rows, replaces connections, and writes the config file in one transaction.
See the source at orchestrator/app/routers/projects.py for the full lifecycle API.

Workspaces

Fork, snapshot, and share a project’s full environment.

Architecture Panel

Visual editor for .tesslate/config.json.

Creating Projects

Template, import, describe.

Agents

How the agent runner drives projects.