Skip to main content
Mirrored from Meerkat Meta main at 26f5ae9da1fd on 2026-11-03; Meta version 0.9.9 at that commit. This walkthrough installs Forge from its public release, connects a model provider, designs a small agent team and installs it on the same computer.
The current release is Meta Forge 0.3.0, a developer alpha published as a prerelease under the tag forge-v0.3.0 in lukacf/meerkat-meta. Download the package for the computer that will run Forge and your applications.

​
Before you start

  • A complete CPython 3.11 installation with venv and ensurepip. Applications install into Forge’s own Python, and the packages in this release are built for CPython 3.11.
  • Internet access for the first start, which installs Forge’s pinned Python dependencies. Node.js, npm and a source checkout are not needed to open Forge.
  • An API key for OpenAI, Anthropic or Gemini.
  • unzip, to extract the package.
Building a custom application (rather than an agent team) has extra isolation prerequisites on Linux.

​
Install Forge and a first agent team

1

Download and verify the package

Download the package and its .sha256 companion:
On Linux, verify it with sha256sum -c "meta-forge-0.3.0-$platform.zip.sha256"; on macOS, use shasum -a 256 -c "meta-forge-0.3.0-$platform.zip.sha256". Continue only when it reports OK.Each package also has a GitHub build attestation. To check it with the GitHub CLI:
2

Unpack it into a folder you will keep

The archive has no top-level folder, so extract it into a new one:
Keep this folder. Forge saves your setups inside it, in .studio. On macOS, keep it outside Desktop, Documents, Downloads, iCloud Drive, cloud storage folders and other volumes if you want installed applications to run in the background.
3

Start Forge

The first start creates Forge’s private Python environment in .venv, installs the pinned dependencies and the bundled SDKs, and checks the bundled Meta and Connect runtime. It then prints the address, normally http://127.0.0.1:8787. Keep the terminal open while you use Forge, and press Ctrl+C to stop it.If your python3 is not CPython 3.11 (Ubuntu 24.04’s is 3.12), install 3.11 and start Forge with it:
To prepare everything without starting the web server or any agents, run bash start.sh --prepare-only.
4

Connect a model provider

Open the printed address. Open Guide settings, select your provider, paste its API key and choose Save locally, then Start guide. Wait for Ready for your first message. The first start may download the guide’s runtime.The key powers Forge’s own agents: the guide, the application builder and the animation programmer. It is saved privately on the computer running Forge and never enters the conversation or downloaded packages. Saving it does not test it; your first message does. You can instead start Forge with OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY set.
5

Describe one useful job

At What would you like to get done?, describe one job, project or recurring task in your own words, or choose Answer two questions for a guided starting point. Nothing is sent until you choose Send to guide.Answer the guide’s questions. Select the answer cards that fit, add context in the composer if you like, and choose Send answer. Say that the team should run on this computer. The proposal and its animation take shape on the right; the animation illustrates the design and does not run your agents.When the design fits and no necessary decisions remain open, choose Use this plan. This saves the design and creates no infrastructure.
6

Install the agent team

Choose Install agent team. When the plan’s destination matches this computer, Forge opens private setup:
  • Project folder: a new empty folder, for example ~/my-app.
  • Console port and the private settings the plan needs, such as model provider keys. To reuse the provider key you gave Forge, select that option explicitly.
Choose Install and start. Forge installs the pinned Meta runtime, checks the selected tool connections, and waits for the agents to start and the Console to report healthy. Private values go to a mode-600 .env in the project folder.
7

Try a real task

Choose Open agent team Console. Sign in if asked, with the Console password you chose during private setup, and select the conversation owner Forge names. Send a small real request and check the answer. Correct a fact and ask a follow-up in the same conversation.
8

Stop and come back

Stop agent team keeps the installed files, private settings and saved state. Stopping Forge with Ctrl+C also stops an application that Forge supervises interactively.Next time, run bash start.sh again in the same folder, choose the setup under Your setups, and choose Start installed agent team. Starting it again resumes the same configured identities.

​
Build a custom application instead

Use a custom application when your outcomes need custom screens or application code. The agent team package does not implement them.
  1. On Linux, install the isolation that application checks need: working unprivileged user namespaces, bubblewrap, libseccomp and the runtime libraries of the checker. On Debian 12 the packages are bubblewrap, libseccomp2, libatomic1 and libstdc++6. On Ubuntu 24.04 and later, also load the distribution’s AppArmor profile for bubblewrap:
    On macOS, checks use the system’s sandbox-exec.
  2. Open Build and checks. If Forge asks for it, choose Prepare app checks. Forge downloads a private, checksum-verified Node.js checker into its own folder and confirms that it starts inside the isolation. This does not start an agent.
  3. Choose Build application. The builder writes application code and tests, and an independent reviewer checks them. The builder can repair the reviewer’s findings automatically, for up to two rounds.
  4. Optionally, open Try with sample data (optional) and run an Agent design or Built application trial.
  5. In the installation panel, under What to install, choose Custom application - independently checked build, a project folder and the private settings. Then follow the action Forge offers: Install and start, or Install application followed by Prepare application setup and Set up and start application when they are offered.

​
Install an agent team package yourself

Download agent team package gives you a ZIP to install yourself, for example on a Linux computer when you prepared a Linux plan on a Mac. Extract it into a new empty folder on the destination, open the folder that contains install.sh and start.sh, and run:
install.sh needs Python 3.11 or newer. It installs the pinned Meta release, checked against its published SHA-256 values, asks for credentials and keeps them in a private .env. If installation stops, follow its printed recovery steps and retry from the same folder. After startup, open the Console URL printed in the terminal. The package’s own README.md lists its exact steps, and the reference describes every command. A custom application built on the release’s selected Meta and Toolkit runtime cannot be installed this way: its install.sh and start.sh refuse and send you back to Forge. Install, set up, update and recover it from its saved setup in Forge.

​
Next steps

  • Concepts: what Forge saves, builds and checks, and how updates work.
  • Reference: settings, files and blueprint fields.
  • Troubleshooting: startup, build and installation messages.