How Cial works
Cial is a per-person AI workspace platform. Your instance is its own running app, not a seat in a shared one — a web UI plus a server, with your data on its own storage. Cial runs a real coding agent (your chosen harness) with full read/write over the workspace, including the platform's own source, so the agent can build what you ask, then rewrite, rebuild, and redeploy Cial itself.
The shape to keep in mind: the browser talks to Cial; Cial runs the agent; the agent operates your instance. Cial is the platform — it manages the harnesses, models, tools, context, and the self-edit pipeline; the agent (your chosen harness) is the engine it runs for each turn. When you chat, Cial routes your message to the agent and streams the result back. Everything below is detail on those parts.
Anatomy of an instance
One app, four parts that ship together. The instance is deliberately disposable compute — cheap to recreate; anything that must outlive a rebuild is committed to your own git fork (see Self-editing & updates).
Because the agent has source access, it isn't a chatbot on a fixed app — it can reshape the app you're using, then deploy the change live.
The harness
Every session runs on a harness — the coding-agent engine that powers each turn. You pick one from the composer when you start a session; the session remembers it, so different conversations can run on different engines.
Both are real coding agents with read/write workspace access; they differ only in the model and the account they authenticate with. Claude Code is the baseline; spin up a Kimi session any time to compare. See Models & harnesses.
The turn lifecycle
A turn is one round: you send, the agent works, the result streams back. Under the hood the browser holds a live socket to your server, the server spawns a fresh harness for the turn, and output streams back over the same socket.
- Send — browser pushes your message into the active session over the socket.
- Prepare — server validates the session, rejects a second concurrent turn, persists the message, and assembles context + enabled tools + attachments.
- Run — server spawns the chosen harness for this turn in a clean environment.
- Stream — text, reasoning, and tool calls render live as the agent works.
- Persist — on finish the result is stored locally; engine state carries to the next turn.
A session runs one turn at a time — a message sent mid-turn queues until the current one finishes. This serialization is also what keeps a shared session coherent across multiple people.
How context reaches the agent
Context is assembled fresh per turn from exactly what you've enabled for the session — nothing carries over implicitly.
- Knowledges — filesystem doc bases. Attaching one injects its instructions plus a file listing; the agent reads files on demand. A built-in knowledge describing the app is always present, which is what enables self-editing.
- Tools (vault) — granted capabilities: an env-var secret, an external MCP server, or a markdown snippet. Only session-enabled tools are wired in.
- Uploads — files attached to a message, stored locally and read by the agent.
- Skills —
/-commands the harness already knows how to run.
See Context: knowledges, tools, uploads, skills.
Calling a secret-bearing vault tool returns the secret into the conversation. In a shared session everyone sees the chat — be deliberate about surfacing secrets.
Where your data lives
Your instance holds your data. Sessions, messages, uploads, knowledges, and tool settings live on the instance's own storage — never pooled into a shared multi-tenant store. The instance is disposable compute, so anything that must survive a rebuild is written to your own git fork of the source.
The boundary: day-to-day data is local; a self-edit becomes durable the moment the agent commits it to your fork. See the applied-vs-saved boundary.
Team collaboration
On a team, instances connect through a shared relay. This never merges instances — each person keeps their own private instance, compute, and data. The relay is a message bus, not shared compute: it carries only collaboration signals.
Three surfaces ride the relay, each rendered in your own UI:
See Collaboration. On a solo setup there's no relay — these surfaces show just you and light up once you're on a team.
Self-healing
Because the agent can rebuild and restart the app it runs in, a bad change is a recoverable event, not downtime. Two mechanisms make that safe.
- Supervisor. The server never restarts itself — a small process outside it does. On deploy the server exits and the supervisor immediately respawns it on new code; on crash it respawns after a short pause. Either way, the app returns.
- Git checkpoints + build rollback. Every saved change is a checkpoint on your fork, and the built UI can revert to the last good build on its own. A broken deploy is undoable, and committed work survives every restart.
If you land somewhere broken, tell the agent plainly — "undo the last change" or "put things back the way they were." Describe the outcome; let Cial work out the steps. Full detail in Self-editing & updates.
Recap
- Instance — its own app (UI + server + agent), with your data stored privately.
- Agent — a real coding agent that does your work and rewrites/rebuilds/ redeploys Cial itself.
- Turn — runs your chosen harness (Claude or Kimi), serialized one at a time, streamed live.
- Context — knowledges, tools/vault, uploads, skills, assembled fresh per turn.
- Team — collaborates over the relay without merging instances.
- Recovery — supervisor restarts + git checkpoints make a bad build safe.
Next: Sessions & harnesses · Context · Extending Cial · Collaboration.