Valet|Docs

Evaluate

How Valet works

On this page

The parts

Valet has a control plane that decides what should run, a gateway that carries traffic, and a separate isolated runtime for every running workload.

  • Control plane. The API behind the CLI, the dashboard and the MCP server. It records what each organization has published, and builds, starts and stops what should run.
  • Gateway. Receives every request to an artifact, app or agent. It checks access, serves artifact files, forwards app traffic, and delivers messages to agents.
  • Runtimes. Each agent and each app process runs in its own isolated runtime: a lightweight virtual machine in the cloud, or a Fargate task in a dedicated installation.
  • Builds. A build turns an app's Node.js, Python or Go source into something Valet can run. Each build runs in its own short-lived runtime.
  • Artifact hosting. An artifact's files sit in object storage. The gateway serves them directly, so an artifact runs no server process.
  • Skill library. Each skill is a Git repository, and each version is a commit. Coding agents read skills through the MCP server or the CLI, and Valet copies the skills attached to an agent into its release. See Skill library.
  • Model proxy. Agents, and apps that attach a model, call models through it. It works with any model behind an Anthropic-compatible or OpenAI-compatible API, holds the providers' API keys, and records each call. See Models.
  • Connector proxy. Agents and artifacts reach MCP-server connectors through a proxy in the gateway, which adds the stored credential to each call.
  • Dashboard. The web interface: everything the organization has published, its connectors and skills, and its members.
  • MCP server and CLI. How coding agents work with Valet. Both call the same control plane API. See MCP server and CLI.
  • Sign-in. People sign in through WorkOS, in both ways of running Valet.

How a publish flows

You ask your coding agent to publish something, and you get back a URL your team can open. In between:

  1. The agent reads your organization's skills. It calls get_skill with governance, then reads the skills that one names, such as security, dependencies and design-system. These are Valet's defaults until your organization publishes its own. See Governance.

  2. It calls a publish tool. Over MCP, that's publish_site for an artifact, publish_app for an app, or publish_agent for an agent. From a terminal, it's valet deploy. Publishing updates an existing artifact, app or agent. To create an empty one with an address, use create_service over MCP, valet sites create or valet apps create. valet agents create creates an agent and deploys it in one step.

  3. The files become a commit, then a release. Each artifact, app and agent has its own git repository. An agent that can run Git pushes a commit to it, sending only what changed, and valet deploy does the same. Files sent in an MCP call become a commit on Valet's side. Then:

    • For an artifact, Valet stores the files and makes the release live.
    • For an app, a build installs the dependencies that package.json, requirements.txt or go.mod names. The app's processes then start on the new release.
    • For an agent, Valet builds the release and starts the agent's runtime on it.

    When your organization has release policies, Valet evaluates the release before it goes live. A blocking policy can refuse it, and the current release stays live.

  4. The gateway routes the URL. Each artifact and app lives at https://<name>.<org>.valet.run in the cloud, or under its own domain in a dedicated installation. Activating a release moves that address to the new release, so the next request gets it.

  5. The gateway checks access on every request. A new artifact or app is private to the organization. You can make it public or put it behind a password.

An app's build takes longer, so your agent waits for it to finish, then opens the URL.

Publishing a skill takes fewer steps. The agent creates the skill with create_service and the kind skill, pushes its files like any other publish, then calls publish_skill. Valet checks the SKILL.md and makes the commit the skill's next release. A skill has no build. It has its own private address, where your team can read it. Coding agents get the new release the next time they read the skill.

How a request flows

When a teammate opens an artifact or app:

  1. It checks who's asking. A public artifact or app is served at once. For a private one, a visitor who isn't signed in goes through Valet's sign-in, which needs no prompt if they're already signed in to the dashboard. Then the gateway checks that the person is a member of the organization that owns it. It checks again on every request, so removing a member ends their access at once.
  2. It serves the request. An artifact's files come straight from storage. An app's request goes to its web process, without Valet's session cookie, so the app never sees it.
  3. It wakes an idle app. An app with no recent traffic stops. The next request restarts it and waits for it to be ready.
  4. It records the visit. Each request produces an access event, which a log drain can export.

A password-protected artifact or app shows a password form instead of sign-in. An artifact can also be shared with someone outside the organization by email; that person gets a guest session for that one artifact.

Releases and source

Every artifact, app and agent has its own git repository. Every publish adds a commit and creates a numbered release that records the commit it was built from. A skill has a repository too: its main holds the latest version, and each version is a commit. See the skill library. In a dedicated installation, the repositories stay inside the installation.

To get the source out:

  • get_source over MCP reads the files of an artifact, app or agent, at the live release or an earlier one.
  • get_source with git: true returns a read-only Git URL for the same release instead, so an agent that can run Git clones it whole. The URL works for an hour.
  • valet sites download <name> copies an artifact's deployed files to a local folder.
  • valet releases files <name> lists the files in an agent's deployed release, and valet releases read <name> <path> prints one.

There is no rollback command. To go back, read an earlier release with get_source and publish those files again, which creates a new release.

Where it runs

Building works the same way in the cloud and in a dedicated installation. In the cloud, Valet runs every part for you. A dedicated installation runs every part in its own AWS account; see What runs in the account.

Sign-in and model calls still reach outside services; see What leaves the installation.

Next steps