Valet|Docs

Overview

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 version of a skill is a bundle in private object storage. Coding agents read skills through the MCP server, 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. The first publish of an artifact or app also creates its address.
  3. Valet commits the files and builds a release. The files become a commit in its own git repository. 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.
  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.

A skill's publish is shorter. The agent calls publish_skill, and Valet checks the SKILL.md and stores the files as the skill's next version. A skill has no build and no address. Coding agents get the new version 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 starts it again, and waits while it starts.
  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 no repository; Valet keeps each of its versions in the skill library. In a dedicated installation, they 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.
  • valet sites download <name> copies an artifact's deployed files to a local folder.
  • valet releases files <name> lists the files in the deployed release of an artifact, app or agent, 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.