Miner Guide - Phylax

Overview

A Phylax miner registers a Bittensor axon on netuid 486 and responds to PhylaxSynapse requests from validators. Each request contains a skill bundle to analyse. You run your analysis pipeline on that bundle and return a signed SSSA. The subnet team defines the structural contract for what inputs you receive and what outputs you must produce. Your internal analysis pipeline is entirely your own. That is where you compete.

The reference repo ships a working harness for every skill type. Running the reference harness unmodified earns Tier 1 (Reference) emissions. To earn Tier 2 or Tier 3 you must replace the internal analysis logic with your own implementation.

Requirements

Docker 24+ with the compose plugin (docker compose version must work)
btcli (install guide)
16 GB RAM, 4 or more CPU cores, 80 GB free disk
Inbound TCP port 8091 open to the public internet (validators dial this port)
Your shell user in the docker group: sudo usermod -aG docker $USER && newgrp docker

Setup

Create Wallet and Register

btcli wallet create --wallet.name miner --wallet.hotkey default

Fund the coldkey with testnet TAO from the Bittensor Discord #faucet channel.

btcli subnet register \
  --netuid 486 \
  --subtensor.network test \
  --wallet.name miner \
  --wallet.hotkey default

Verify:

btcli wallet overview --wallet.name miner --subtensor.network test

Install and Configure

curl -fsSL https://raw.githubusercontent.com/praxi-labs/phylax-subnet/main/scripts/install.sh | bash -s miner

Edit ~/phylax/miner/.env:

Variable	What to set
`PHYLAX_NETUID`	`486`
`SUBTENSOR_NETWORK`	`test`
`WALLET_NAME`	folder name in `~/.bittensor/wallets/`
`WALLET_HOTKEY`	`default` (or the hotkey you registered)
`PHYLAX_SERVER_URL`	network server URL
`PHYLAX_SERVER_HOTKEY`	pinned server hotkey

If you started the miner before fixing these, docker compose restart is not enough. Env vars are only read at container creation. Run docker compose up -d --force-recreate.

Choose Your Skill Types

You decide which skill types to support. No one assigns them. Pick what you have the infrastructure and expertise to do well.

Skill type	What the bundle contains	What your harness must do
`rag_knowledge`	Documents, knowledge base content. No code.	Content scan. No sandbox. Compute fingerprint, detect hidden instructions, enumerate URLs, find the canary.
`declarative`	A `SKILL.md` of natural language instructions. No code.	Static text analysis. No sandbox. Compute `skill_md_fingerprint`, run prompt injection classifier, detect Unicode anomalies, find the canary.
`executable_python`	Python source plus dependency manifests.	Static analysis + SBOM + Docker sandbox detonation. Emit four base traces plus `imports.jsonl`. Thread canary through sandbox.
`executable_script`	Shell scripts.	Static shell taint analysis + Docker sandbox detonation. Emit four base traces plus `shell_commands.jsonl`.
`mcp_server`	MCP server with handlers and manifest.	Two containers (server + your test client). Enumerate and exercise all tools, one invocation carrying the canary. Emit four base traces plus `tool_calls.jsonl`. Compute `mcp_manifest_hash`.
`agent_composition`	Composition manifest orchestrating child skills.	Multi container cascading detonation across parent and all children. Emit aggregated base traces plus `agent_calls.jsonl`. Compute dependency graph hash and transitive risk score.

declarative is mandatory and automatic. The register helper and the server both inject it for you, so you only list the EXTRA types in PHYLAX_SUPPORTED_TYPES. You must declare at least one extra type, and rag_knowledge alone does not count. Valid additions: executable_python, executable_script, mcp_server, agent_composition (or rag_knowledge plus one of those four).

Build Your Pipeline

The reference repo ships a working harness for every skill type that earns Tier 1 emissions out of the box. To reach Tier 2 or Tier 3, replace the internals with your own analysis logic.The installer clones the source into ~/phylax/miner/src/. All paths below are relative to that directory.

Skill type	Runner file	Sandbox container
`rag_knowledge`	`src/phylax/harness/rag_knowledge/runner.py`	none
`declarative`	`src/phylax/harness/declarative/runner.py`	none
`executable_python`	`src/phylax/harness/executable_python/runner.py`	`src/phylax/harness/executable_python/container/`
`executable_script`	`src/phylax/harness/executable_script/runner.py`	`src/phylax/harness/executable_script/container/`
`mcp_server`	`src/phylax/harness/mcp_server/runner.py`	`src/phylax/harness/mcp_server/container/`
`agent_composition`	`src/phylax/harness/agent_composition/runner.py`	`src/phylax/harness/agent_composition/container/`

Each runner exposes run(bundle_dir, nonce, canary_id, canary_val). Your replacement must return the same dataclass shape and emit the required trace files into the evidence directory.For runtime types, the container contract:

Entrypoint: /harness/run.sh <bundle_path> <nonce>
Env vars injected by the runner: CANARY_ID, CANARY_VAL, AGENT_TIMEOUT
All required JSONL trace files written to /evidence/ which is bind mounted by the runner

Log Into Your Container Registry

Before you build and push, you must be logged into the registry where the image will live. The build helper does not handle this for you. You can use any public registry: Docker Hub, GHCR, Quay, ECR Public.

Docker Hub
GHCR (GitHub)
Quay / ECR Public / other

docker login

Username and password are from hub.docker.com. Free accounts get unlimited public repos. Validators pull anonymously.

Generate a personal access token at github.com/settings/tokens with the write:packages scope, then:

echo "<your-pat>" | docker login ghcr.io -u <your-gh-username> --password-stdin

After the first push, go to the package settings page on GitHub and change visibility to Public, otherwise validators get 403 when they try to pull and your reputation tanks.

Use the registry’s own login command:

docker login <registry-host>

Confirm the destination repo is public before pushing.

The <namespace> in your image tag must match your username on that registry. For example, an image tagged docker.io/alice/phylax-sandbox-python:v1 can only be pushed by the user alice. A mismatched namespace produces push access denied ... insufficient_scope: authorization failed.

Build and Tag Your Sandbox Image

The cloned source ships a helper at src/scripts/build-sandbox.sh that handles the build, push, and digest extraction for you.

cd ~/phylax/miner

# Build and push in one go
./src/scripts/build-sandbox.sh executable_python <registry>/<your-username>/phylax-sandbox-python:v1

Replace <registry> with docker.io, ghcr.io, quay.io, etc. Replace <your-username> with your registry username (this must match the account you logged in with in the previous step).The helper prints the registry image and the sha256: digest at the end. Paste both into your .env:

PHYLAX_SANDBOX_IMAGE=docker.io/<your-username>/phylax-sandbox-python:v1
PHYLAX_SANDBOX_DIGEST=sha256:<digest from the helper output>

If you prefer to build manually, the Dockerfile lives at src/phylax/harness/<skill_type>/container/Dockerfile. The build context must be the container/ directory because the Dockerfile uses COPY tracer.py ... relative to itself:

cd ~/phylax/miner/src/phylax/harness/executable_python/container

docker build -t docker.io/<your-username>/phylax-sandbox-python:v1 .
docker push docker.io/<your-username>/phylax-sandbox-python:v1
docker inspect --format='{{index .RepoDigests 0}}' \
  docker.io/<your-username>/phylax-sandbox-python:v1

PHYLAX_SANDBOX_DIGEST must exactly match the image_hash you register in the next step. Validators verify this on every primary submission.

After pushing, verify the image is publicly pullable from any machine that has never seen your registry credentials:

docker logout
docker pull docker.io/<your-username>/phylax-sandbox-python:v1

If this fails, the repo is private and validators will not be able to rerun your sandbox.

Validators only route tasks to miners with a current specialization on file. The cloned source ships a helper at src/scripts/register.sh that reads your .env, signs a request with your hotkey, and POSTs it to the server.Run it once after you’ve edited .env, and re-run whenever you change PHYLAX_SUPPORTED_TYPES or rebuild the sandbox image.

cd ~/phylax/miner

# First time only: install the signing dependency
pip3 install --user substrate-interface

# Register
./src/scripts/register.sh

Expected output:

==> POST https://<server>/v1/specialization/register
    hotkey: 5DLAsRvTzGpLTbMEBfFoVgX6vt1uVAJqPeDtDbMU2PpXgf2G
    types:  ['executable_python', 'declarative']
    image:  docker.io/<you>/phylax-sandbox-python:v1
    digest: sha256:8f2328f24aef3e23...
==> 200 OK
{"hotkey":"...","supported_types":["executable_python","declarative"], ...}

Every runtime type you declare needs a sandbox image. The script applies PHYLAX_SANDBOX_IMAGE / PHYLAX_SANDBOX_DIGEST to all runtime types in PHYLAX_SUPPORTED_TYPES. If you build separate images per skill type, edit .env and re-run the script for each one, or call src/scripts/register_miner.py directly with a custom .env per type.

PHYLAX_SANDBOX_DIGEST must exactly match what you pushed to your registry. Validators pull and rerun this image to verify your traces.

Run

cd ~/phylax/miner
docker compose pull
docker compose up -d
docker compose logs -f

Within about 30 seconds you should see:

Axon serving on [::]:8091

When a validator dispatches a task:

scan: bundle=sha256:... type=executable_python profile=standard task=...
scan done: sha256:... -> ALLOW risk=12

Primary vs Auditor Role

Every task carries a task_metadata.role field set to either primary or auditor. The validator chooses your role per task per round. You do not choose it.

Primary
Auditor

Three primaries per task, picked from the highest reputation for that skill type.Submit:

Full SSSA
trace_bundle (for runtime types)
sandbox_manifest (for runtime types)
probe_evidence

Get the full timing window from the profile timing matrix.Earn full emission.

Two auditors per task, picked randomly from declared miners outside the top 3.Submit:

Full SSSA (verdict, findings, capabilities, dependencies, policy)
probe_evidence
No trace_bundle required
No sandbox_manifest required

Get a tighter timing window (see below).Earn 0.6 × primary_emission × consensus_score.

If you have been an auditor for the same skill type three rounds in a row, you are rotated into a primary slot regardless of reputation rank.

Auditor timing windows

Skill type	Primary t_min / deadline	Auditor t_min / deadline
`rag_knowledge`	5s / 45s	2s / 15s
`declarative`	10s / 90s	3s / 30s
`executable_python`	30s / 300s	10s / 90s
`executable_script`	30s / 300s	10s / 90s
`mcp_server`	60s / 600s	20s / 150s
`agent_composition`	120s / 900s	30s / 240s

The windows above are for the standard profile. fast and deep profiles scale accordingly.

What You Must Submit Per Task

Return the same PhylaxSynapse with these fields populated.

1. attestation (always required, primary and auditor)

The signed SSSA. Full structure described in SSSA Schema.

2. probe_evidence (always required, primary and auditor)

A dict derived from the synapse nonce.

{
  "file_path":    "/skill/.probe_<sha256(nonce)[:16]>",
  "file_content": "<sha256(nonce)[16:48]>",
  "dns_host":     "<sha256(nonce)[:8]>.probe.phylax.ai",
  "process_echo": "<sha256(nonce)[8:24]>"
}

For runtime skill types your harness must also perform these three events inside the sandbox so they appear in fs.jsonl, network.jsonl, and process.jsonl.

3. trace_bundle (required for runtime primaries only)

dict[str, str] of {filename: base64(gzip(jsonl_bytes))}.

Skill type	Required files
`executable_python`	`network.jsonl.gz`, `fs.jsonl.gz`, `process.jsonl.gz`, `secrets.jsonl.gz`, `imports.jsonl.gz`
`executable_script`	`network.jsonl.gz`, `fs.jsonl.gz`, `process.jsonl.gz`, `secrets.jsonl.gz`, `shell_commands.jsonl.gz`
`mcp_server`	`network.jsonl.gz`, `fs.jsonl.gz`, `process.jsonl.gz`, `secrets.jsonl.gz`, `tool_calls.jsonl.gz`
`agent_composition`	`network.jsonl.gz`, `fs.jsonl.gz`, `process.jsonl.gz`, `secrets.jsonl.gz`, `agent_calls.jsonl.gz`
`rag_knowledge`, `declarative`	Omit entirely

Size caps (compressed): network 5 MB, fs 10 MB, process 5 MB, secrets 1 MB, imports 2 MB, shell_commands 5 MB, tool_calls 5 MB, agent_calls 10 MB. Total bundle must not exceed 30 MB.

4. sandbox_manifest (required for runtime primaries only)

{
  "image":          "ghcr.io/<you>/phylax-sandbox-python:v1",
  "digest":         "sha256:abc123...",
  "tracer_version": "1.0.0",
  "tracer_hash":    "sha256:def456...",
  "kernel":         "",
  "cpu_arch":       ""
}

image and digest must exactly match what you registered.

Canary Handling

Every task carries a canary_id and canary_val derived from the nonce. You must handle them correctly or your evidence score is zero.

Skill type	What to do with the canary
`rag_knowledge`	Compute `rag_content_fingerprint` over the documents exactly as delivered. Scan for `CANARY_<canary_id>` in content and set `canary_id_found` accordingly.
`declarative`	Scan SKILL.md for `<!-- CANARY: {canary_id} -->`. Set `canary_id_found = true` when found. Compute `skill_md_fingerprint` over SKILL.md exactly as delivered.
`executable_python` / `executable_script`	Thread `canary_val` into the sandbox as the `CANARY_VAL` env var. Have your harness write it to `/skill/.canary` before launching the skill. Your tracer must record this filesystem op in `fs.jsonl`.
`mcp_server`	Include `canary_val` as a parameter value in at least one synthetic tool invocation. The record must appear in `tool_calls.jsonl`.
`agent_composition`	Inject `canary_val` into the parent skill’s input context before detonation. The propagation must appear in `agent_calls.jsonl`.

Hard Rules

Break any of these and your SSSA scores zero for that task.

No LLM for analysis

Using a live LLM to decide the verdict, score prompt injection, classify tool poisoning, or analyse skill content is forbidden. LLMs are only permitted for post-analysis enrichment.

No skill_type mismatch

Return an SSSA whose skill.skill_type differs from the task’s skill_type and the response is treated as invalid.

No early responses

Return before task_metadata.t_min_s and the response is treated as not having run the sandbox.

No late responses

Return after task_metadata.deadline_s and the submission is discarded entirely. No score, no reputation update.

The only permitted LLM allowed_use values are finding_enrichment, mitre_owasp_mapping, or cve_explanation. Any other value scores zero and flags your hotkey for a reputation penalty.

How the Validator Verifies You

In the same round

The validator decompresses each trace file, normalises with ts-sorted JSON, and recomputes the sha256. The hash must equal what you declared in the SSSA. The validator also scans your fs.jsonl for the canary write and checks your probe_evidence matches the nonce derivation.

Across your verification group

The validator dispatches the same bundle to 5 miners (3 primaries + 2 auditors). After all responses arrive, the validator computes consensus across verdict, findings, capabilities, dependencies, and policy. Your consensus score multiplies your emission. See Consensus.

Asynchronously for the next round

The validator pulls your registered sandbox image, verifies its digest matches what you registered, and reruns it on the same bundle and nonce. Pass adds +0.02 to your per type reputation. Fail multiplies by 0.7. Result feeds into the next round.

Configuration Reference

Variable	Default	Description
`SANDBOX_TIMEOUT`	`60`	Per detonation timeout in seconds
`PHYLAX_LOG_LEVEL`	`INFO`	Log level
`PHYLAX_EVIDENCE_HOST_DIR`	set by install.sh	Host side absolute path of the evidence bind mount. Required for docker in docker.
`PHYLAX_SANDBOX_IMAGE`	`ghcr.io/praxi-labs/phylax-sandbox:latest`	Image launched by runtime harnesses. Must match `image_uri` at registration.
`PHYLAX_SANDBOX_DIGEST`	(empty)	`sha256:...` digest of the sandbox image. Must match `image_hash` at registration.
`PHYLAX_TRACER_VERSION`	`1.0.0`	Tracer version string included in `sandbox_manifest`
`AXON_PORT`	`8091`	Host port for the miner axon

Troubleshooting

Container exits immediately

Hotkey not found. Check ls ~/.bittensor/wallets/<WALLET_NAME>/hotkeys/<WALLET_HOTKEY> exists.

No scan: lines after 5 minutes

Either not registered with the network, or axon unreachable. Re-run the registration step. Check inbound 8091.

Specialization rejected: 'sandbox_images must include an entry for each runtime skill type'

You declared a runtime type (e.g. executable_python) but PHYLAX_SANDBOX_IMAGE / PHYLAX_SANDBOX_DIGEST are missing or empty in .env. Set both and re-run register.sh.

Specialization rejected: 'needs base_weight >= 1.0'

PHYLAX_SUPPORTED_TYPES is empty or only contains rag_knowledge. Add at least one of executable_python, executable_script, mcp_server, agent_composition to your .env.

Specialization rejected: 'missing sandbox_image'

Runtime type declared without a sandbox image entry. Add sandbox_images[<type>] for every runtime type you declared.

Sandbox produces only log.txt

Evidence bind mount misconfigured. Re-run scripts/install.sh or set PHYLAX_EVIDENCE_HOST_DIR to the correct absolute host path.

permission denied connecting to Docker API

Container UID not in host docker group. Confirm DOCKER_GID matches getent group docker.

Bundle hash mismatch

Wrong bytes downloaded. Check bundle_url is reachable from inside the container.

Sandbox timeouts

Heavy bundle or slow analysis. Increase SANDBOX_TIMEOUT.

SSSA Schema

Field by field reference for the signed attestation.

Probe Events

How probe events are derived and verified.

Scoring

How your submission is scored.

Reputation

How per type reputation evolves.

​Overview

​Requirements

​Setup

​Primary vs Auditor Role

​Auditor timing windows

​What You Must Submit Per Task

​Canary Handling

​Hard Rules

No LLM for analysis

No skill_type mismatch

No early responses

No late responses

​How the Validator Verifies You

​Configuration Reference

​Troubleshooting

​Next

SSSA Schema

Probe Events

Scoring

Reputation

Overview

Requirements

Setup

Primary vs Auditor Role

Auditor timing windows

What You Must Submit Per Task

Canary Handling

Hard Rules

How the Validator Verifies You

Configuration Reference

Troubleshooting

Next