Vercel fx: Tiny Native Coding Agent for Developers

Vercel’s experimental fx project takes a deliberately small approach to agentic coding: a native Zig binary, a shell-like interface, explicit permissions, resumable sessions, ACP support, and an experimental WebAssembly SDK.

Vercel has introduced fx, an experimental coding-agent harness and terminal CLI designed for developers who want an AI coding assistant that feels closer to a Unix tool than a heavyweight IDE. According to the official documentation, fx is written in Zig, distributed as an approximately 6 MB native binary, and built to run in local terminals, automation environments, editor integrations, and embedded WebAssembly applications.

The project is available at fx.sh, with documentation, a browser-based demonstration, and source code published by Vercel Labs. Its current status is explicitly experimental: users should expect frequent changes and should evaluate it carefully before adopting it in critical production workflows.

What is fx?

fx is not presented as another full IDE. It is a compact agent harness: a runtime that accepts natural-language requests, reads a project, invokes tools, streams model responses, and applies changes under a permission and sandbox policy.

The product’s design is centered on a few principles:

• Small footprint: the native binary is described as roughly 6 MB.
• Fast startup: fx is designed for a very short cold-start path and minimal work before accepting input.
• Shell-like ergonomics: output favors a terminal transcript over a visually dense IDE interface.
• Embeddability: the same core can be used through a native CLI, an Agent Client Protocol (ACP) server, or an experimental WebAssembly SDK.
• Model and provider flexibility: fx can work with local models, gateways, direct provider APIs, or supported subscriptions.
• Controlled agency: tool calls pass through permissions, rules, session grants, and sandbox decisions.
• Composable capabilities: skills, plugins, MCP servers, web search, vision, and subagents extend the core without turning the runtime into a monolith.

This positioning matters because many coding agents optimize primarily for an interactive desktop experience. fx instead targets developers who want to place an agent inside existing terminal workflows, CI jobs, editor clients, browser applications, or resource-constrained sandboxes.

Why the tiny binary matters

The practical advantage of a small native executable is not just download size. A compact runtime can reduce friction in environments where installing a full JavaScript application stack is undesirable or impossible.

Potentially useful environments include:

• ephemeral development containers;
• CI runners and build workers;
• remote development hosts;
• internal developer tools;
• agent sandboxes;
• terminal-first workflows;
• applications that need many lightweight agent instances;
• browser products that want to expose a controlled coding-agent experience.

The official site describes fx as having a minimal memory footprint and a cold start intended to be close to instant. Those claims should be treated as product goals rather than independent benchmark results, but they explain the project’s architecture: fx is trying to keep the runtime small enough to be embedded and automated rather than requiring a persistent IDE shell.

Getting started with fx

The official installer supports macOS and Linux on x86_64 and arm64. The quick-start command is:

1curl -fsSL https://fx.sh/setup.sh | bash

The installer places the binary in ~/.local/bin by default and can update the user’s shell profile when that directory is not already on the PATH. The documentation also recommends reviewing the installer first when local policy requires it:

1curl -fsSL https://fx.sh/setup.sh -o setup.sh
2less setup.sh
3bash setup.sh

That review step is important for any tool installed by piping a remote script into a shell. The fx documentation notes that the installer downloads release archives over HTTPS but does not currently verify a published signature or checksum. Teams with stricter supply-chain controls should pin versions and apply their own artifact-verification process.

After installation, verify the binary and local environment:

1fx --version
2fx doctor

fx doctor can report the workspace, configuration, authentication, resolved startup settings, local session state, and Git integrations without beginning an agent turn.

To update an installation, use:

1fx upgrade

The project also documents building from source with Zig 0.16 or newer:

1git clone https://github.com/vercel-labs/fx.git
2cd fx
3zig build -Doptimize=ReleaseSafe
4./zig-out/bin/fx --version

Authentication and model access

fx supports two primary authentication paths.

Sign in with Vercel

For an interactive local setup:

1fx login

This opens a Vercel authorization flow and stores the OAuth session in ~/.fx/auth.json, refreshing it when needed. Headless environments can set FX_NO_OPEN_BROWSER=1 to print an authorization URL instead of opening a browser.

Use an AI Gateway API key

The interactive setup flow is:

1fx setup

The documentation says that macOS stores the key in Keychain, while Linux stores it in ~/.fx/api-key with permissions restricted to the current user. For CI, the recommended approach is to store the credential in the CI provider’s secret manager and expose it only to the relevant job through AI_GATEWAY_API_KEY.

fx selects credentials in this order unless the user explicitly chooses a source through /setup:

1. VERCEL_OIDC_TOKEN, when supplied by a Vercel runtime;
2. AI_GATEWAY_API_KEY for the current process;
3. a saved fx login session;
4. a key saved through fx setup.

Teams can switch the active Vercel team with:

1fx teams

The active team affects AI Gateway requests, the model catalog, and Gateway credit checks. Developers can inspect the active model, credential source, team, permission mode, sandbox, workspace, and update channel with:

1fx status

The security rule is straightforward: do not place API keys in .fx.json, project instructions, or source code.

The interactive workflow

Start fx from the project that should be treated as the primary workspace:

1cd path/to/project
2fx

A useful request names real files, directories, or commands rather than asking for an abstract answer. For example:

1Read src/ and explain how requests are routed. Add a test for the router's error path, then run the test suite.

fx works in turns. The model response streams into the transcript while tool calls appear as they run. Developers can interrupt a turn with Escape or Ctrl+C, and Ctrl+O opens Review and the full transcript.

The shell also exposes slash commands for model selection, permissions, status, session management, MCP configuration, and other runtime controls. Typing / opens the available command list.

Permissions are part of the product design

A coding agent is only as safe as the boundary around its tools. fx routes every tool call through a permission runtime before execution.

Workspace listing, globbing, searching, and reading are generally non-approval operations. More sensitive operations can require review, including:

• writing or editing files;
• deleting, renaming, or copying files;
• creating directories;
• running commands;
• opening paths outside the workspace;
• installing skills;
• using vision capabilities.

fx separates permission decisions from sandbox decisions. Permission determines whether a call may execute. The sandbox determines what an allowed command can do while it runs.

The documented modes are:

The default is auto. Users can switch modes inside fx:

1/permissions ask
2/permissions auto
3/permissions yolo

Persistent allow and deny rules live in ~/.fx/settings.json. Workspace-specific rules can be narrower than global rules. A team might allow routine test commands while denying destructive Git operations, for example:

1{
2  "permission": {
3    "*": "ask",
4    "bash": {
5      "git *": "allow",
6      "git push *": "deny"
7    },
8    "edit": {
9      "docs/*": "allow",
10      "*": "deny"
11    }
12  }
13}

The documentation is clear that yolo is process authority, not a harmless convenience switch. It bypasses fx policy and command sandboxing for that run, so it should not be used casually on a developer laptop containing sensitive repositories.

Resumable sessions and recovery

Interactive conversations are saved under ~/.fx/sessions/. This lets developers leave a project and return to the same agent context later.

Useful commands include:

1fx sessions
2fx session last --json
3fx -r
4fx resume last
5fx ask --resume last "continue with the tests"

fx also persists partial responses, tool progress, and recovery checkpoints. Interrupted work can be continued interactively with /continue or from a headless workflow with:

1fx ask --resume last --continue-recovery

Long sessions are compacted to keep model context useful. After eight completed turns, fx keeps the latest four turns verbatim and condenses earlier work into a record of requests, outcomes, evidence, and interruptions. The saved transcript remains intact; compaction changes what is sent to the model on future requests.

This is a practical feature for debugging and multi-step migrations. Instead of copying a long conversation into a new prompt, a developer can resume the workspace session and continue from the recorded state.

fx ask for scripts and CI

The interactive shell is useful for exploration, but automation needs a noninteractive interface. fx ask runs one request and exits:

1fx ask "explain what this repository does"

Standard output can carry the assistant’s Markdown while progress and diagnostics remain on standard error. Structured automation can use JSON:

1fx ask --json "summarize the current changes"

The JSON response can include the assistant output, exit code, model, session ID, number of steps, and tool-call statuses. That makes it easier to integrate fx into scripts that need to distinguish a successful explanation from a failed or interrupted run.

For visual tasks, attach an image:

1fx ask --image ./ui.png "describe this interface"

A --no-save option is available for runs that should not create a session. In CI, remember that fx ask cannot pause for an interactive human approval. Saved permission rules still apply; unresolved calls can stop the run. The --auto option can review unresolved requests automatically, while --yolo disables the safety boundary and should be reserved for controlled environments.

ACP turns fx into an editor backend

fx can run as an Agent Client Protocol (ACP) server for compatible editors and clients:

1cd /absolute/path/to/project && fx acp

A client can launch the absolute binary with the acp argument:

1{
2  "command": "/absolute/path/to/fx",
3  "args": ["acp"]
4}

The client’s working directory becomes the primary workspace, and the documentation recommends a separate server process for each primary workspace.

ACP exposes methods for initialization, creating and loading sessions, resuming and closing sessions, listing sessions, prompting, cancelling prompts, changing configuration, and changing modes. It uses newline-delimited JSON-RPC 2.0 over standard input and output, with an 8 MiB limit for each input message.

The server reuses fx settings for authentication, project instructions, skills, sessions, permissions, sandboxing, and tools. One important integration detail is that ACP sessions use only the mcpServers supplied by the client; they do not automatically inherit the native profile at ~/.fx/mcp.json.

For editor vendors and internal developer-platform teams, this makes fx interesting as a small backend rather than only a terminal application.

WebAssembly and embedded applications

The experimental WebAssembly SDK is one of fx’s most distinctive capabilities. Because fx is written in Zig, it can build as a native executable or WebAssembly module.

The SDK exposes two main paths:

createFxTerminal() can render fx through a terminal component such as xterm.js. createFxAgent() exposes sessions through a JavaScript API backed by ACP, allowing an application to render its own interface.

The SDK currently depends on JavaScript Promise Integration (JSPI). The documentation lists support in current Chrome and Edge versions and newer Safari releases, while Node.js 24 requires the experimental JSPI flag.

A simplified headless example looks like this:

1const agent = await createFxAgent({
2  wasm: './fx-core.wasm',
3  env: {
4    AI_GATEWAY_API_KEY: 'development_key_only',
5  },
6})
7
8const session = await agent.createSession()
9const turn = session.prompt('Explain this project')
10
11for await (const update of turn) {
12  if (update.sessionUpdate === 'agent_message_chunk') {
13    console.log(update.content.text)
14  }
15}
16
17await agent.close()

The production warning is critical: do not embed a long-lived AI Gateway key in browser code. A real application should proxy model requests through a backend or use the documented device-login flow.

The WebAssembly build also has narrower capabilities than native fx. It does not include native processes, operating-system sandboxing, keychain access, arbitrary WASI filesystem access, native MCP, subagents, skills, web search, auto-upgrade, clipboard integration, or the full native tool set. The optional workspace adapter can add an application-controlled run_command capability.

In other words, WebAssembly makes fx embeddable, but it does not magically turn a browser into a full local operating-system agent. That boundary is a feature for products that need deliberate control over what the embedded agent can access.

MCP, skills, tools, and subagents

fx is an MCP client. Native sessions read MCP configuration from the trusted profile at ~/.fx/mcp.json; repository-local MCP files are intentionally not loaded, preventing a cloned repository from silently adding a server.

fx supports local stdio servers and remote HTTP or legacy SSE servers. Protected servers can use environment-backed headers, bearer-token environment variables, or OAuth with PKCE. Literal Authorization headers are rejected so secrets do not become ordinary profile data.

MCP tools are discovered lazily. The model searches for relevant tools and selects schemas only when needed, reducing context usage in installations with large tool catalogs. Dynamic MCP calls pass through the same permission policy as built-in tools.

That architecture is useful, but MCP configuration remains sensitive. A server process or remote endpoint executes with the authority it receives, and server output is untrusted input. Keep ~/.fx/mcp.json private, use narrowly scoped credentials, and review external tool behavior before granting access.

Beyond MCP, fx supports reusable skills, project instructions, web search, vision, and subagents. Together, these capabilities let teams keep the core runtime small while adding domain-specific behavior only where it is needed.

fx compared with a traditional IDE coding agent

fx is not automatically a replacement for an IDE agent. It is better understood as a lower-level, more composable runtime for people who want terminal control, automation, editor protocol support, or embedded experiences.

Who should evaluate fx?

fx is especially relevant for:

• terminal-first developers who prefer shell workflows;
• teams building internal coding-agent platforms;
• CI and automation engineers who need structured agent output;
• editor and IDE developers looking for an ACP backend;
• browser-product teams exploring embedded agents;
• organizations that want explicit tool permissions and local session storage;
• researchers studying small, embeddable agent runtimes.

It may be a poor fit for teams that need a stable, polished IDE experience today, broad native integrations out of the box, or a mature enterprise support lifecycle. The project is experimental and the documentation warns that frequent changes are expected.

Security and operational checklist

Before using fx on a real repository:

1. Review the installer or pin a version in automation.
2. Keep API keys in a credential store or CI secret manager.
3. Start in ask or auto mode rather than yolo.
4. Use narrow permission rules for repetitive commands.
5. Treat MCP configuration and server output as sensitive.
6. Avoid embedding long-lived browser-side credentials.
7. Test ACP clients with a disposable workspace first.
8. Understand the difference between permission approval and sandbox access.
9. Check fx status and fx doctor when behavior is unexpected.
10. Keep the experimental status in mind before placing fx in a production control plane.

Frequently asked questions

Is fx made by Vercel?

Yes. The official site describes fx as a project from Vercel Labs, and the source repository is published under the Vercel Labs GitHub organization.

Is fx open source?

The fx site describes it as open source under the Apache-2.0 license.

What language is fx written in?

fx is written in Zig and can build as a native executable or WebAssembly.

Does fx require a Vercel account?

Not necessarily. The documented authentication options include signing in with Vercel or supplying a Vercel AI Gateway API key. The project also aims to support local models and direct provider access depending on the configured model and provider path.

Can fx run in CI?

Yes. fx ask is designed for noninteractive scripts and CI, supports JSON output, and can resume saved sessions. CI jobs should use secret managers and preconfigured permission rules because interactive approval prompts are unavailable.

Does the WebAssembly SDK include all native fx features?

No. The WebAssembly SDK has a deliberately narrower capability set and does not include native processes, operating-system sandboxing, native MCP, subagents, skills, web search, or the complete native tool set.

What is ACP in fx?

ACP stands for Agent Client Protocol. fx can run as an ACP server so compatible editors and clients can create sessions, send prompts, receive streamed updates, and manage configuration through a standard protocol.

Bottom line

fx is an ambitious experiment in making coding agents smaller, more composable, and easier to embed. Its combination of a compact Zig binary, shell-like workflow, structured fx ask interface, resumable sessions, ACP server, MCP client, explicit permissions, and WebAssembly SDK gives it a broader surface area than a simple terminal chatbot.

The most important qualification is maturity. fx is experimental, its APIs and behavior may change, and several capabilities—especially WebAssembly embedding—are still documented as experimental. Developers should evaluate it in a controlled repository, verify the permission boundary, and pin versions in automation.

For teams that want an AI coding agent to behave like a Unix component—small, scriptable, protocol-aware, and embeddable—fx is a project worth watching.

Official sources

• fx official site
• fx documentation
• fx documentation index
• Installation
• Authentication
• Sessions
• fx ask
• ACP server
• WebAssembly SDK
• Permissions
• MCP
• fx source repository

Disclosure: This article is based on the official fx.sh documentation and public project materials. fx is experimental; commands, APIs, and product behavior may change.