---
title: Forge
emoji: 🛠️
colorFrom: yellow
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---

# Forge

A self-improving assistant you talk to like a person. Ask it to do something; if it doesn't
already have the tool for the job, it writes one and puts it in front of you for approval
before it ever runs. If an approved tool breaks, it patches itself and sends the patch back
for approval too.

## How it works

- **Chat** — plain conversation, backed by your Inference Port API.
- **Tools** — small JavaScript functions (`async function run(args) { ... }`) that Forge
  writes on demand and calls like normal functions once approved.
- **Approval gate** — nothing Forge writes runs until you hit *Approve* on its ticket card.
  Decline it and Forge is told why (if you give a reason) so it can try something else.
- **Self-healing** — if a tool throws, Forge automatically drafts a fix and files it as a new
  ticket. The broken tool keeps its old code until the fix is approved.
- **Sandboxing** — tool code runs in a restricted `vm` context with a timeout, not a fully
  hardened sandbox. The approval step is the real safety boundary — read the code before
  approving it, same as you would review a PR.

## Setup

1. **Set Space secrets/variables** (Settings → Variables and secrets):
   - `INFERENCE_API_URL` — the chat completions endpoint for your Inference Port API.
     Double-check this is current before deploying; see `.env.example` for the last known value.
   - `INFERENCE_API_KEY` — your key, as a **secret**, not a variable.
   - `INFERENCE_MODEL` — defaults to `llama-3.3-70b-versatile` if unset.
   - `AGENT_NAME` — optional, defaults to `Forge`.
   - `USE_PERSISTENT_STORAGE` — set to `true` to store tools at `/data/forge-tools`
     (requires persistent storage enabled in Space settings).

2. **Persistence.** Tools are written to `/data/forge-tools` if the **`USE_PERSISTENT_STORAGE`**
   env var is set to `true` **and** the Space has persistent storage enabled, otherwise they
   fall back to a local folder that's wiped on every rebuild. Turn on persistent storage in
   Space settings and set `USE_PERSISTENT_STORAGE=true` if you want tools to survive restarts.

3. Push this repo to your Space. The `Dockerfile` builds and runs it on port 7860.

## Local dev

```bash
npm install
cp .env.example .env   # fill in your values
npm start
```

Then open http://localhost:7860.