# How Zenitya works

Zenitya turns your team's workflows into tools that every agent in the
organization can call. You write a tool once in TypeScript, deploy it with
`zya deploy`, and grant it to the people and service accounts who need it.
They reach it from Claude, Codex, Cursor or any MCP client through one
connection.

A tool replaces a chain of model turns with one deterministic call: the same
input gives the same result every run, and the agent spends its tokens on the
task instead of on rediscovering how to do it.

## The pieces

**Organization.** Everything belongs to an organization: its members, projects,
groups and keys. You sign in with Google and pick the organization once; the CLI
and MCP connections remember it.

**Project.** A unit of deployment, usually one repository. A project has a
`zenitya.json`, an entrypoint that registers tools with `@zenitya/sdk`, and
optionally a `skills/` folder. `zya deploy` uploads the source and Zenitya
builds it remotely. Projects do not get their own endpoints: every project's
tools join one pool for the organization.

**Tool.** A name, a JSON schema for its input, optional output schema, hints
such as `readOnlyHint`, and an `execute` function. Agents see a tool as
`<project>.<tool>`, for example `orders.refund`. See [Writing tools](tools.md).

**Skill.** An [Agent Skill](https://agentskills.io/specification): a
`SKILL.md` with instructions for how your organization works and when to use
which tool. Skills deploy with a project and agents read them over MCP. See
[Publishing skills](skills.md).

**Group.** Groups decide who can call what. Everyone is in the Default group;
owners and admins create more groups, add people and service accounts to them,
and grant tools and skills to each group. A person can call the tools of
Default plus every group they belong to. Roles (owner, admin, member) decide
who can manage and deploy; they never grant tools by themselves.

**Service account.** A non-human member for CI, scripts and bots. It holds
machine keys with explicit scopes (`deploy`, `invoke`, `configure`) and gets
tools through its groups. See [Machine keys and CI](ci.md).

**Connected MCP server.** Owners can also connect existing MCP servers, such
as Linear or Sentry, and serve their tools through the same endpoint and
groups as your own.

## Where code runs

`zya exec --local` runs a tool's source on your machine with Bun, for fast
iteration. Everything deployed runs in Zenitya's cloud, in an isolated
microVM per project. Deployed tools have no internet access unless the project
turns on egress, and they read [secrets](secrets.md) as environment variables.

A deploy only changes what agents see once its build passes. A failed build
leaves the previous deployment serving calls.

## How agents reach tools

| Who                     | How                                                         |
| ----------------------- | ----------------------------------------------------------- |
| A person in their agent | MCP at `https://api.zenitya.com/mcp`, signing in with OAuth |
| A person in a terminal  | `zya exec <tool>` in the project's directory                |
| CI, a script or a bot   | A service account key, over MCP or the CLI                  |

See [Connecting agents over MCP](mcp.md).

## Next

- [Quickstart](quickstart.md): your first tool, deployed, in a few minutes.
- [Working with an agent](agents.md): let a coding agent do it for you.