A place to begin.

INSTALL

Run Field locally.

Install Node.js 22.13 or newer. Download the source archive, extract it, and open a terminal in the field folder. npm comes with Node.js.

npm ci
npm run db:setup
npm run dev -- --port 3001

Open http://localhost:3001, then enter your space. Keep the terminal running. The database step asks you to confirm the migration and creates your local workspace storage; it does not require a Cloudflare account. If PowerShell blocks npm, use npm.cmd instead.

The source download contains application code and Nia’s character assets. It excludes saved workspaces, model keys, deployment credentials, and the hosted project binding.

Try a first interaction.

I’m home
Move to the window
Remember: I prefer quiet mornings
Task: Plan a weekend walk

Demo mode recognizes a limited set of commands. Connect a model for open-ended conversation. Tasks are saved to-dos; recording one does not execute work outside Field.

CONNECT

Change the model. Keep the companion.

The model generates each response. Field carries the continuing context: identity, saved memories, relationships, notes, and plans. A new connection begins with that same saved state.

Run Nia on your computer.

Install Ollama, then start the local model service. Qwen3.5 9B is the starting model for this setup; its download is about 6.6 GB. Keep the service running while you use Field.

npm run model:serve

npm run model:pull

Copy .dev.vars.example to .dev.vars, preserve existing settings, and use the values below. Restart Field, then enter your space. The local connection is selected automatically; conversations and saved history stay on this computer. No API key is needed.

FIELD_AI_ENABLED="true"
FIELD_AI_PROVIDER="ollama"
FIELD_AI_MODEL="qwen3.5:9b"
FIELD_AI_CONCURRENCY="1"
FIELD_AI_VISITOR_TURNS="100"

This setup handles one response at a time. First use can take longer while the model loads. Local responses have no per-message API fee; the computer still provides the memory, power and compute. A published cloud site cannot reach this computer through localhost.

Connect another model.

ollama list

OLLAMA_ORIGINS="http://localhost:3001" ollama serve

Let visitors begin without a key.

When the site owner enables Field’s shared connection, visitors can enter their space and start talking. Each browser keeps its own saved history. Field reads that history on the server and sends selected context to DeepSeek; replies appear as they arrive.

For your own installation, copy .dev.vars.example to .dev.vars. Keep your existing local settings. Supply your key, a daily budget, and current provider rates there, then enable the service and restart Field. Never put a real key in frontend code or a source archive.

FIELD_AI_ENABLED="false"
FIELD_AI_PROVIDER="deepseek"
FIELD_AI_KEY=""
FIELD_AI_MODEL="deepseek-v4-flash"
FIELD_AI_DAILY_USD=""
FIELD_AI_INPUT_USD_PER_MILLION=""
FIELD_AI_OUTPUT_USD_PER_MILLION=""
FIELD_AI_VISITOR_TURNS="20"
FIELD_AI_SITE_TURNS="1000"
FIELD_AI_CONCURRENCY="4"
FIELD_AI_MAX_OUTPUT="1200"

Fill both rates in USD per million tokens using the provider’s current standard prices. Allowances reset at midnight UTC. Failed or stopped attempts still use an allowance because the provider may have processed them. The server reserves an estimated maximum cost before each call; provider billing limits remain separate. An unconfigured installation stays in demo mode.

CUSTOMIZE

Shape her presence.

For an existing workspace, edit the name and personality in Identity. The same panel lets you control moving, notes, and tasks. These controls update saved settings directly.

Change defaults in code.

In lib/field.ts, the profile inside initialWorkspace() supplies defaults for new workspaces. Exact earlier built-in personality text upgrades to the current default; custom names and personalities remain yours.

profile: {
  name: 'Nia',
  purpose: COMPANION_PURPOSE,
},

Nia’s identity, interests, small contradictions, voice, portrait reference and palette live in lib/companion-character.ts. Her complete character, visual and voice specification is in docs/nia.md. The runtime combines that definition with the action contract in lib/entity.ts. Keep permissions and response validation intact when changing her manner.

Adjust the 3D appearance.

The current spatial character is authored in lib/companion-avatar.ts. The skin material applies to her face, neck, ears, hands, and legs.

skin: '#633b2c',
skinDetail: '#40251d',

The portrait is a separate image at public/characters/nia-v1.png. Editing a mesh color does not recolor the portrait.

CONTINUITY

Your history has a home.

Running the whole app locally keeps workspace data in the local D1 emulator under .wrangler/state. On the hosted site, workspace data lives in its hosted D1 database—even if you use Ollama for responses.

Use Export agent in Identity to download a portable snapshot. Importing replaces the receiving workspace after a preview and backup; model credentials are excluded and the connection resets.

Keep a copy before changing machines. Avoid sharing exported agent files casually: they contain the memories and relationship details you chose to save.

Check your changes.

npm run typecheck
npm run lint
npm test
npm run build

The build also refreshes the clean source download. Each browser receives a separate guest workspace, with server-side access checks. Guest access uses a private cookie rather than an account. Clearing cookies or changing devices starts a new space; use an export to carry your history with you.

Shared inference, visitor allowances, global budgets and concurrency limits are implemented. A public launch still needs a funded provider account, operational abuse controls and a deployment. Anonymous cookies do not provide cross-device account recovery. Demo mode makes no model calls.

THE COMPANION RUNTIME

Follow every request.

In your space, open Memory to pin a priority or preview recall for a message. Open Runtime to inspect the last 40 requests, including incomplete, failed, and cancelled attempts.

Relevant memory, with a budget.

Field ranks saved memories with local BM25 keyword search. Pinned entries come first, then relevant matches. If nothing matches, recent memories provide a fallback. At most eight memories are included, with a 1,000-character excerpt limit per memory and 6,000 text characters overall. These limits cover memory text, not the entire model prompt.

The inspector records memory IDs, scores, selection reasons, excerpt lengths, and an approximate memory token count. Provider token counts, when available, are the actual full-request usage. The retrieval is lexical, not embedding-based semantic search. Saved memory text remains user-controlled.

She remembers you. You still get to change.

In Memory, choose Correct this understanding on a current statement. Write what fits now, preview the change, and review your open plans and room notes. Keep each item as it is, rewrite it, or remove it from the space. Confirming applies your correction and chosen edits together. Calculated findings retain their original evidence and cannot be rewritten this way.

Earlier wording moves to History and is excluded from recall, even if pinned. Each correction links two versions; repeated corrections and exports preserve that chain. Deleting a newer record never reactivates its earlier version. Both versions count toward the 200-record memory limit.

Context matches identify plans or notes created while that memory, or an earlier version, was available to a model. This records exposure, not causation. Unlinked items are also listed for your review. Field does not automatically rewrite a plan or cancel anything outside the space.

A correction starts a fresh conversation context. Earlier messages and action receipts stay in your history but are excluded from future prompts. Identity, relationships, other current memories, and reviewed plans remain available. Local and hosted adapters use the same rule. This prevents old dialogue from being replayed; it does not guarantee that a model will never make an incorrect inference.

A response has a lifecycle.

Persist request + recall plan
  → call the selected provider
  → validate the structured response
  → recheck current action permissions
  → commit reply + actions + run result together

A run uses a snapshot of context captured at its start. The response must still pass permissions against current state. A correction made during inference rejects the old response and its entire action batch; send the message again with current memory. Cancelled and rejected responses apply no model actions. A reply and its successful action batch become one workspace update, protected by the same revision check as other data.

Shared responses are committed on the server. Reopening your space loads the saved outcome; expired unfinished shared requests are marked as failed. Field does not automatically retry inference. Use the save indicator’s Retry to reconcile an uncertain result. Your own model connections can leave an unfinished run if their tab closes before saving.

Inspect outcomes, without keeping secrets.

Runs retain provider and model names, start and finish times, status, categorized failures, token usage when reported, and IDs of committed receipts. They do not store keys, raw provider payloads, extra copies of memory text, or hidden model reasoning. Runtime text is resolved from current workspace records, so a deleted memory is not reconstructed from a trace.

Open your space →

TROUBLESHOOTING

If something gets in the way.