Local Dev Setup

Running freezr on your own machine is the most comfortable way to build apps for it. You get the in-browser App Creator, your app folders sit on your own disk where your editor and your AI coding agent can reach them, and — because it is your machine — you can point freezr at the Claude Code or Codex subscription you already pay for, instead of a metered API key.

This page is the whole path, start to finish: install Node, get freezr running, give the Creator an AI, then move to your own editor when you would rather work there. It takes about fifteen minutes.

Looking to host freezr for real, on a server or in the cloud? That is install freezr. This page is specifically about a development machine.

1 · Node & npm

freezr is a Node application. If node --version prints something, you already have what you need — anything reasonably current is fine.

node --version
npm --version

If not, install Node from nodejs.org (the LTS build), or with a package manager — brew install node on a Mac, or nvm if you juggle Node versions. npm comes with it.

2 · Get freezr and install its dependencies

Open a terminal from within the folder you want to install freezr in.

git clone https://github.com/salmanff/freezr.git
cd freezr
npm install

No build step, no bundler — freezr serves its apps as plain files. If you would rather not use git, download the repository as a zip from the same page and unzip it.

3 · First run

npm run dev

That starts freezr in development mode on port 3000. (npm start is the production equivalent.) On a brand-new install, open:

http://localhost:3000/register/firstSetUp

You will be redirected to

/register/firstSetUp

The setup page asks where to keep your data and creates your first user. On a development machine take the defaults — the local file system and the built-in database — which put everything under users_freezr/ inside the freezr folder. Your first user is an admin user.

Keep this terminal. freezr runs in the foreground and logs there. Restart it after changing anything in the server code or in an environment variable — app files themselves are read fresh on each request, so day-to-day app work needs no restart.

4 · Enable AI on your server by adding an API key

freezr's App Creator (which helps you create apps), and many other apps need an LLM to work. The straightforward route is an API key, which you add once at /account/resources (via "Account Settings") → Add LLM Key: Give it a name, pick Claude or ChatGPT, paste your key. (You need to get a key via your Claude or ChatGPT subscription)

Keys are encrypted at rest and never handed to apps — an app asks freezr to make a request, freezr makes it. Usage and cost per app are visible at /account/resourceusage.

Set FREEZR_ENV_KEY before adding credentials. It is the key freezr uses to encrypt stored secrets. Without it they are stored unencrypted. Any long random string will do — set it in your environment before starting the server, and do not change it afterwards or existing secrets become unreadable.

5 · Or use the Claude / Codex subscription you already have

If you already pay for Claude Code or ChatGPT, freezr can drive the CLI installed on your machine instead of spending API credits. Calls then run against your own subscription and report a cost of $0.

freezr never reads, stores or transmits your login for this. It runs the binary you already installed and logged into, and reads its output — there is no token for freezr to hold.

Setting it up

Install and log in to the CLI. Claude Code: curl -fsSL https://claude.ai/install.sh | bash, then run claude once and sign in. Codex: npm i -g @openai/codex, then codex login.
Turn on the server switch. As an admin, go to /admin/prefs and tick "Enable local CLI LLM connectors". It is off by default.
Enable it on your account. At /account/resources a card appears for each CLI freezr can find. Press Enable…, confirm the binary path, and tick the three confirmations — that you administer this server, that the subscription is yours, and that you accept the provider's terms.

It then appears in your LLM list like any other resource, and the Creator can use it.

What we deliberately restrict — and why

These two connectors are more tightly fenced than anything else in freezr. The limits are self-imposed: nothing forces them technically, and we would rather explain them than have them look arbitrary.

By default, only the App Creator can use a local agent. Other apps will not see it as an option, even once you have enabled it. There are two independent reasons, and either on its own would be enough.

The terms. Anthropic allows a subscription holder to use headless Claude Code for their own personal and development work, and prohibits offering claude.ai logins or subscription capacity to other people. A developer using it to build an app is squarely inside that. An ordinary app answering its users out of your subscription is much closer to the line. OpenAI is less restrictive but recommends API keys for automation.

Prompt injection. Codex is an agent, not a plain model. freezr switches its command execution off, keeps it in a read-only sandbox with an empty working directory, and blocks its network access — but no single setting has been proven to remove every action an agent could take. That only matters when a prompt carries text written by someone else — an email body, a chat message, a transcript — because text like that can carry instructions aimed at the model. Ordinary apps are full of other people's text. Building an app is not.

Alongside that, every local-agent call is fenced in ways an API-key call is not:

Admins only, and only when the server-wide switch is on — both re-checked on every single call, so revoking either takes effect immediately.
The CLI gets a stripped environment. It is given only what it needs to run and find your login — not the server's database credentials, encryption key or cloud keys. Your API keys are not passed either, so a configured key can never be billed silently by this route.
Claude runs with no tools at all — prompt in, text out. Codex runs with command execution disabled, read-only, no network, in a scratch directory.
One call at a time, with a queue of one and a hard timeout, so an app cannot burn through your subscription window in a loop.

If you are building something where an app genuinely needs a local agent, and you accept the risks above, a server administrator can lift the app restriction by setting SHOW_LOCAL_AGENT_IN_APPS=true in the server's environment. It is an environment variable rather than a settings checkbox on purpose: it should be a deliberate decision by someone who has read this section, not a box ticked in passing. For anything handling other people's content, use an API key instead.

These restrictions may loosen. They reflect what today's terms allow and what today's tooling can be proven to contain. If either changes, so will the default.

6 · Move to VS Code (or Cursor, or your terminal)

The Creator is the quickest way to get an app started, and you do not have to stay in it. Every app is just a folder on disk, so you can open it in your own editor at any point and keep going with whatever agent you prefer — and come back to the Creator later if you want. Nothing is one-way.

The three helpers that make this work are on your freezr home page at /account/home, under Install Existing Apps → Dev (admins only).

The context file

An agent that has never seen freezr will invent APIs that do not exist. freezr-context.md prevents that: one generated document with the hard rules, the manifest format, the full API reference and the permission patterns — the same guidance the Creator gives its own model. Press "(re)Generate context file for LLMs" to drop the current copy into an app folder; it is also refreshed whenever the app is updated.

Then point your agent at it:

Claude Code — a CLAUDE.md at the app root containing one line: @freezr-context.md. Loaded automatically every session.
Cursor — save it as .cursor/rules/freezr.mdc, or add a rule pointing at it.
Copilot / Codex / most others — rename or symlink it to AGENTS.md.
ChatGPT on the web — upload it to the conversation or the project's files.

Dev tokens

An agent that can only edit files is coding blind — it cannot see whether what it wrote actually works. Press "Regenerate Tokens for App" and freezr writes .freezr-access.local.json into the app folder: a long-lived token with read and write access to that app's own tables, plus ready-made curl examples. The agent can then create a record, read it back, and confirm its own work.

That file is a credential. freezr adds it to the app's .gitignore for you. Keep it that way — never commit it, and never paste its contents anywhere.

The round trip

Edit files, reload the page — app files are read fresh on each request, so there is nothing to rebuild. The one exception is manifest.json: changing pages, permissions or collections means freezr has to re-read it. Press "Regenerate App from Files" on the same Dev tab, and grant any new permission at the app's settings page.

Where things live

`users_freezr/<user>/apps/<app.name>/`	your app's files — point your editor here
`users_freezr/<user>/db/`	that user's data
`users_freezr/<user>/files/`	files uploaded by apps
`/creator`	the App Creator
`/account/home`	your apps, and the Dev tab
`/account/resources`	LLM keys, local agents, connected accounts
`/admin/prefs`	server-wide switches (admins)

Troubleshooting

Port 3000 is busy. Something else is already using it — often an older freezr. On Mac or Linux: lsof -ti :3000 to see what, then lsof -ti :3000 | xargs kill.
The local Claude / Codex card never appears. All three conditions must hold: you are an admin, the switch at /admin/prefs is on, and freezr can find the binary. It looks in the usual install locations — if yours is elsewhere, enable it anyway and type the full path.
"The local CLI is not logged in." Run claude (or codex login) in a terminal on that same machine and sign in. freezr uses the CLI's own login and cannot do this for you.
"Usage limit reached." Your subscription's window is exhausted. Wait for it to reset, or switch to an API key for the moment — both can be configured at once, and you pick per request.
An agent writes code using APIs that do not exist. It has not been given freezr-context.md. See the context file.
A new permission or page is ignored. The manifest changed, so press "Regenerate App from Files" — see the round trip.