Install a genome

How installing works

A genome is a file of plain-language genes in the AGF 1.0 format. Installing means putting those genes into an agent platform that can read the format. The file can come from any source: a pack on Nixtra, a colleague, or one you made yourself in the builder. The steps are the same.

Where it can be imported today

IntelliNix is the only platform with an importer, and it needs a workspace with the genome flags on. Nixtra has no importer of its own and no link to IntelliNix: you download here and import there. The file is plain JSON, so you can read it anywhere, but there is no importer for other agent frameworks.

The three steps

Get the file. Download a .agf.json from a pack page, or export one from the builder.
Verify it. Compare its SHA-256 with the checksum on the pack page, or check it in the browser below.
Import it with preview and consent. The import first shows what would change. Nothing is applied until you consent, and you can undo it afterwards.

1. Get the file

On a pack page, use the Download button. The file name on disk is up to you; the examples below use my-genome.agf.json. From the builder, the last step saves the file.

2. Verify it

A pack page publishes the SHA-256 of its file. Replace [PUBLISHED-SHA256] with it. If the answer is not a match, do not import the file.

Check the SHA-256 (macOS and Linux) bash

# Linux
echo '[PUBLISHED-SHA256]  my-genome.agf.json' | sha256sum --check -
# macOS
echo '[PUBLISHED-SHA256]  my-genome.agf.json' | shasum -a 256 --check -

Check the SHA-256 (Windows) PowerShell

$expected = '[PUBLISHED-SHA256]'
$actual = (Get-FileHash -Algorithm SHA256 -LiteralPath 'my-genome.agf.json').Hash.ToLower()
if ($actual -eq $expected) { 'Matches the published checksum' } else { "Does NOT match. This file is $actual" }

Or check it here. The file is read in your browser and is not uploaded.

Check a genome file you downloaded. The file is read in this browser. It is not uploaded.

Published checksum (optional)

Paste the SHA-256 from the pack page to compare. Leave it empty to check the file on its own.

Genome file (.agf.json)

Choose the file, or drop it here. Files over 256 KB are refused before they are read.

3. Import it with preview and consent

In IntelliNix an administrator imports a file in three separate steps. Preview reads the file and stores a record of what would change, and writes nothing to any agent or workspace list. Consent applies the preview. Undo takes the import back in one step; if lists changed since, you are warned first and must confirm. A preview is kept for 7 days.

An administrator imports. Only the administrator who made a preview can apply it when it holds personal-layer genes.
The built-in core (germline) and identity genes in a file are never imported. The destination agent keeps its own.
A learned gene does not become active. It becomes a proposal that someone reviews.
A gene already there is left alone. A different gene with the same id is refused, not overwritten.
Genes for a layer that is switched off in the workspace are skipped, and the preview says so.

The screens are described in the IntelliNix guide. The same three steps by script:

Preview, apply and undo with curl bash

# 1. Preview. This writes only a transfer record. Nothing is applied.
#    Into the workspace layers only:
curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/workspace/import/preview' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  --data-binary '@my-genome.agf.json'

#    Or into one agent and the workspace layers:
curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/agents/[AGENT-ID]/import/preview' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  --data-binary '@my-genome.agf.json'

# 2. Read the answer. Copy its "id" into [TRANSFER-ID] below, then read "genes", "skipped" and "rejected".
#    Apply only if you agree with every line.
curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/transfers/[TRANSFER-ID]/consent' \
  -H 'X-API-Key: [YOUR-API-KEY]'

# 3. To undo the import in one step:
curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/transfers/[TRANSFER-ID]/undo' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"confirm_later_changes":false}'

Status of each way to install

Each row says whether it works today. A row that says “Not available yet” is not built on the platform side, and the guide for that target says what to use instead.

Status of each way to install a genome
Way to install	Status	Details
IntelliNix (import) Import in Settings, Workspace policy, Transfer	Needs an IntelliNix workspace with the genome flags on	Preview, consent and undo. The Transfer section appears only when the agent_genome and genome_format flags are on for the workspace, and only an administrator can import.
Python SDK import methods (import_preview, import_consent, import_undo)	Not available yet	The methods exist in the SDK, but the routes they call are not mounted on the platform. Each call raises NotFoundError (404).
Python Plain HTTP script against the workspace import routes	Needs an IntelliNix workspace with the genome flags on	Python standard library only. Same flags and administrator rule as the IntelliNix import.
Python Check the file checksum with hashlib	Works today	Needs nothing from IntelliNix.
JavaScript SDK import methods	Not available yet	The JavaScript SDK has no import methods.
JavaScript fetch against the workspace import routes	Needs an IntelliNix workspace with the genome flags on	Node 18 or newer. Same flags and administrator rule as the IntelliNix import.
REST Workspace import routes under /genome	Needs an IntelliNix workspace with the genome flags on	Preview, consent and undo with curl. Needs the agent_genome and genome_format flags and an administrator.
REST Import through the public /genome/v1 API	Not available yet	The /genome/v1 import routes are not mounted. The public API can read, compile and export a genome, not import one.
MCP Import a pack through MCP	Not available yet	The genome MCP endpoint has six tools and none imports a file.
MCP Read, compile or export the genome of an agent already in your workspace	Needs an IntelliNix workspace with the genome flags on	Needs the genome_public_api and agent_genome flags and an API key with the genome scopes.
Verify the file Check a downloaded file in your browser, or with sha256sum, Get-FileHash or hashlib	Works today	The browser check needs JavaScript on this page. The command-line checks need nothing from Nixtra or IntelliNix.
One-click install from Nixtra into IntelliNix A button on a pack page that installs it into your workspace	Not available yet	There is no link between the two sites. You download the file here and import it there.

One-click install is not available. There is no sign-in with IntelliNix here and no button that installs a pack for you.

Common problems

The checker on this site, and the import on the platform, refuse a file for a few clear reasons. The first column is the code this site's checker gives. The second is the code the platform answers with.

Common problems with a genome file, what they mean and how to fix them
Checker code	Platform code	What you see	How to fix it
`too_large`	`too_large`	The file is over 256 KB, or holds more than 200 genes. The size limit is checked before the file is parsed. The platform refuses the import and stores nothing.	Remove genes you do not need, shorten long gene text, or split the file in two. The builder shows how close you are to both limits.
`unsupported_agf_major`	`unsupported_agf_major`	The file says it is AGF 2.0, or any version whose first number is not 1. Readers here read AGF 1.x only. The second number does not matter, so 1.0 and 1.3 both work.	Ask the publisher for an AGF 1.x export. Do not change the number by hand: a new first number can mean different rules.
`invalid_agf_version`	`invalid_agf_version`	The agf field is missing, or is not written like "1.0". The version is the first thing a reader checks, so nothing else in the file is read.	Check that you chose a genome file and not another JSON file. If you built it by hand, add "agf": "1.0".
`forbidden_reference`	`forbidden_reference`	A gene lists a source (provenance) that could identify a person, such as a user id, an email address or an execution id. A shared genome must not carry personal references. The only allowed forms are a src: pseudonym, share:explicit, promoted:, parent:, import: and derived:runs.	Remove the entry from the gene, or set provenance_mode to none and remove all of them. Then export again so the digest is recomputed.
`invalid_json`	`invalid_json`	The file is not valid JSON. Most often it was cut short, saved with a different encoding, or copied with extra text around it.	Download the file again and do not open and save it in a word processor.
`digest_mismatch`	`digest_mismatch`	The digest stored in the file does not match its contents. The file was edited after the digest was written. The platform refuses such a file.	Download the original again. If you edited it on purpose, open it in the builder and export it again: the builder writes a new digest. A new digest hides that a file was edited, so compare with the published checksum when it came from someone else.
`schema`	`invalid_document`	A required field is missing or has the wrong type, for example no exporter, a bad timestamp or a wrong layer name. The validator names the path of the field, such as layers[0].stratum.	Open the file in the builder or the Verify section below. Each problem names the field to fix.
`invalid_gene`	`invalid_document`	One gene breaks a rule: empty or over-long text (400 characters), a strength outside 0 to 1, an unknown kind, or a kind in a layer where it is not allowed. The message names the gene by id, never by its text.	Fix the gene named in the message.
`duplicate_gene_id`	`invalid_document`	Two genes share an id. Ids must be unique across the whole file, including the core.	Give one of them a new id.

Not errors: genes the preview leaves out

A preview can be fine and still leave some genes out. It lists them with a reason, and you decide whether to go on.

Reasons a preview leaves genes out
Reason	Listed under	Meaning
`needs_agent`	`skipped`	Customer and learned genes need an agent to import into. A workspace import has none.
`layer_flag_off`	`skipped`	The layer these genes belong to is not turned on in your workspace.
`team_not_chosen`	`skipped`	The file has team genes and no team was chosen.
`layer_unavailable`	`skipped`	The personal layer is not available to you.
`id_conflict`	`rejected`	A different gene with the same id is already there. Nothing is overwritten.

Answers from the import routes

If you import with a script, these are the HTTP answers and what to do.

HTTP answers from the import routes
Answer	What it means	What to do
401	The credentials were not accepted.	Check the key or token. A suspended or deleted account is refused with 403.
404	Not found. The same answer is used when a feature flag is off, when the agent or transfer id does not exist, and when it belongs to another workspace.	Ask a workspace administrator to turn on agent_genome and genome_format. Check the agent id or transfer id.
403	You are not allowed. The import routes need the settings update permission (an administrator). Applying a preview that holds personal-layer genes is allowed only for the administrator who made it.	Use an administrator account, and apply with the same account that made the preview.
422	The file was rejected, or nothing in it can be imported. The message starts with a code such as too_large, invalid_json, invalid_agf_version, unsupported_agf_major, invalid_document, forbidden_reference or digest_mismatch. Nothing is stored for a rejected file.	See the common problems table on the install page, then fix the file and preview again.
409	The step cannot happen now: the memory changed since the preview (stale), the preview is older than 7 days (expired), the transfer is not in a state that allows the step (invalid_transition, for example applying twice), or the memory changed while applying (conflict, and none of the import is kept).	Preview the file again, then apply.
409 on undo	Lists changed after the import. The answer has code later_changes and a count, and nothing is written.	Read the warning. To undo anyway, send the undo again with confirm_later_changes set to true.

Before you rely on a pack

A passing checksum shows you have the published file. It does not show the genes are right for your business. Read every gene. For packs marked as regulated, have a qualified person read them. Nixtra gives no legal, tax or medical advice.

Guides: all integration guides, IntelliNix, REST, Python, JavaScript, MCP.