DocsAgentsProject workspace

The project workspace.

How projects, runs, jobs, and workspace sessions compose. The four objects you'll see most often, the relationships between them, and how state survives between them.

§ 01Projects

A project is the top-level container. Everything else in the workspace — files, runs, sessions, artifacts, history — belongs to exactly one project.

Projects are per-user. Two users in the same organization each have their own set of projects, and the platform enforces strict tenant isolation: every workspace operation is scoped to a (user_id, project_id) tuple, and the agent runtime cannot read across that boundary even when prompted to.

Projects are cheap. The right granularity is roughly one project per unit of work that has its own files: an account, a deal, a matter, a quarter, a customer. Don't try to make one mega-project hold everything; isolation is what gives you replayability and clean history.

TipProjects survive forever unless you delete them. Files, runs, and artifacts inside a project stay available for as long as the project does, so use the project as your archive as well as your live workspace.

§ 02Workspace sessions

A workspace session is the runtime context the agent acts inside. It is the live link between you, the project, and the four surfaces — terminal, browser, IDE, preview.

Sessions are ephemeral. They are bound 1:1 to a (user_id, project_id) pair: at most one active session per user per project at a time. When you open a project the platform attaches an active session if one already exists, or provisions a fresh one if not.

Lifecycle

A session has a configurable TTL — by default, twelve hours from creation. Inside the TTL the session stays warm: terminal scrollback persists, browser cookies persist, the file tree is up to date.

Sessions are auto-revoked in a few cases:

Logout. Logging out terminates every session belonging to that user immediately.
TTL expiry. Sessions older than their configured TTL are cleaned up.
Project deletion. Deleting a project terminates the session bound to it.
Explicit revoke. You can revoke from the UI; admins can revoke from the platform side.

Persistent project state (files, run records, artifacts, history) is independent of session lifecycle. A session ending does not lose your work — it loses the live shells and browser tabs.

§ 03Runs

A run is one execution of an agent against one prompt. Every chat message that triggers the agent produces a run.

Each run has:

A status — queued, running, completed, failed, cancelled.
A started_at and completed_at timestamp.
Token totals for input and output, against the model that was used.
A timeline of events — tool calls, tool results, terminal output, browser sessions, surface switches, artifact creations.
A list of artifacts the run produced, if any.

Runs are immutable once complete. You can re-run a prompt — that produces a new run — but you cannot edit a finished run in place.

§ 04Jobs

A job is a structured alternative to free-form chat. Where a chat run takes a sentence and an optional file, a job takes a typed input — a contract to summarize, a meeting to take notes from, a deal to write an executive brief on — and produces a typed output: a summary, a memo, a CSV, a deliverable bundle.

Jobs are pre-built. They ship with their own skill bundles, output schemas, and verification loops. You don't have to write a prompt; you fill in the fields the job asks for, hit run, and the agent produces the deliverable in the format the job specifies.

The full catalog is on the Skills & jobs page. The short list: Accountant, Invoice Extractor, AP Manager, Meeting Notes, Contract Summary, Executive Brief, Architect, RFP Responder, SOW Builder, Underwriting Brief.

§ 05Directory layout per project

Every project has a small set of well-defined areas, and the agent knows the meaning of each.

project layout

project/
├── drive/         # User uploads — pdf, docx, xlsx, csv, txt, json, images
├── workspace/     # Scratch space for the agent during a run
├── artifacts/     # Deliverables saved with save_output()
└── knowledge/     # Per-session memory of file reads, terminal output, chat

Drive is yours. You upload here. The agent reads from here.
Workspace is the agent's. Intermediate files, scratch artifacts, working copies. Cleared between runs unless explicitly preserved.
Artifacts are the deliverables — saved by the agent through save_output(), listed on the run record, downloadable.
Knowledge is the agent's memory of past reads, terminal output, and chat. It survives within a session and is what lets the agent answer follow-up questions without re-reading the same files.

For the full file rules and supported formats, see Drive & artifacts.

§ 06History

Every run is persisted forever (until the project is deleted). The history panel for a project lists every past run with its prompt, status, duration, and any artifacts. From there you can:

Replay the run as a typed event timeline — see exactly what the agent did, in order, with the inputs and outputs of every tool call.
Re-open artifacts and download or copy them.
Re-run with the same prompt or a tweaked version. The original run is preserved as a separate record.
Audit for cost, token usage, latency, and outcome.

NoteHistory is the audit trail. Compliance, governance, and post-hoc review all read from the same persistent run records — there is no separate "audit log" to enable.

§ 07Where to go next

Learn the surfaces the agent acts through → Surfaces.
Learn how the runtime parallelizes via subagents → Runtime & subagents.
Learn how files flow through a run → Drive & artifacts.