Skip to content

Convex-Dev/convex / .claude/skills/local-network

local-network

Verified

Run isolated local Convex networks and in-process lattice node networks for development. Use when testing against local peers, reproducing peer or P2P replication issues, exercising NodeServer or P2PNode sync, or when no remote network is configured.

FileKindSize
SKILL.mdskill md12.5 KB
---
name: local-network
description: Run isolated local Convex networks and in-process lattice node networks for development. Use when testing against local peers, reproducing peer or P2P replication issues, exercising NodeServer or P2PNode sync, or when no remote network is configured.
---

# Run a Local Convex Network

A local network is the default way to exercise changes in this repository. It
needs no credentials, no remote host, and can be thrown away and recreated
freely. Prefer it over a remote network for anything that is not specifically
about remote behaviour.

Requires a built `convex.jar` — see the `build-convex` skill.

## Start a Temporary Network

```bash
java -jar convex.jar local start
```

Starts a throwaway test network. State is not preserved between runs, which is
what you want for testing.

Useful options:

| Option | Effect |
|--------|--------|
| `--count N` | Number of peers to launch |
| `--ports ...` | Specific peer ports (default: assigned automatically) |
| `--api-port N` | Port for the REST API |
| `--norest` | Do not start the REST server |
| `--no-tray` | No system tray icon |
| `--protocol-version N` | Pin the protocol version |

## Start with the Peer Manager GUI

```bash
java -jar convex.jar local gui
```

Launches the same local network under the peer manager GUI — useful for
watching consensus and inspecting peer state visually.

## Talking to It

Once running, point the client commands at the local peer:

```bash
java -jar convex.jar client query --host localhost --port <PORT> '(balance #12)'
java -jar convex.jar client status --host localhost --port <PORT>
```

## Notes for Tests

Do **not** start a network from a JUnit test by shelling out to the CLI. Tests
construct peers or lattice nodes in-process.

For consensus/CVM peer tests, follow the fixtures in `convex-peer`. For lattice
replication, use `NodeServer`; for the bundled P2P and social regions, use
`P2PNode`. See `convex-peer/src/test/java/convex/node/LatticeNetworkTest.java`
and `convex-p2p/src/test/java/convex/p2p/P2PSocialSyncTest.java`.

`NodeServer` is schema-independent and replicates an assembled `LatticeHost`. It
owns attached-propagator lifecycle and isolated update
notification, but no lattice, merge policy, socket or transport: the host's
applications own merge semantics. The host owns root retention and durability;
`RelayHost.open` assembles the relay case
of one live application over a whole lattice. It does not publish or interpret
`NodeInfo`, inspect `:p2p` / `:social` paths, or implement discovery policy. The
calling application explicitly creates each `LatticePropagator`; there is no
implicit/default group. `LatticeNode.createPropagator(groupConfig)` creates and
registers a group using the host store, starting it if running; the no-argument
form uses default limits, not the node's config. Identity, filters and handlers
may be configured dynamically. A zero-propagator node
is a valid local persistent node. Each propagator owns its connection manager,
transport identity, trust, bounded protocol endpoint, filters and serving store,
and merges nothing.

The calling application separately owns any `LatticeListener`: register every
eligible propagator, install a connection selector, launch the listener
after the node, and close it before the node. One listener may route connections
to several groups, and groups may instead use independent listeners or custom
transports. Registrations and selectors can change while running; existing sockets
keep their assignment until closed or the group is unregistered. `LatticeNode`
supplies the standard TCP assembly, and `serveAllInbound(group)` explicitly selects
a group for new inbound assignments. `P2PNode` performs its own composition; its `NodeDirectory` owns
signed `[:p2p :nodes]` publication, validation, discovery translation and PoP
metadata. Keep tests for those behaviours in `convex-p2p`, not `convex-peer`.
`P2PNode` also configures its node key explicitly as both its transport challenge
identity and its signed `NodeInfo` owner. A generic `NodeServer` does not infer a
transport key from the host; direct tests set it on the
propagator itself before opening connections. Social user DIDs
and their account keys remain a separate application concern.

For a small lattice network test:

> **CAD036 envelopes:** use `[:LV path value]` for an optimistic push with no
> acknowledgement, and `[:LV id path value]` when the sender needs a Result after
> merge. `Message.withID` upgrades the optimistic form without replacing its path.
> Lattice gossip and root announcements use the lean optimistic form. Every `:LV` and `:LQ`
> path is a vector, with `[]` selecting the root; do not use nil, omitted or scalar
> paths. A four-field `:LV` with a nil ID remains an accepted fire-and-forget wire
> representation, but is not needed for new optimistic pushes.

> **Security model:** P2P data is public, so `serveAllInbound()` may assign an
> untrusted inbound connection to the public propagator view. Assignment is not
> authentication and does not make the connection an outbound gossip route. An
> unverified connection may submit only complete `LATTICE_VALUE` messages; path-aware
> admission runs before persistence, unsolicited `DATA` is rejected, and missing-cell
> acquisition is reserved for verified connections. P2PNode's default social policy
> retains only local users, operator pins and direct active follows. The separate
> inbound upgrade verifies both challenge signatures, a random nonce, responder and
> challenger audiences, the fixed lattice-peer context and an admitted signed
> NodeInfo. Shared-listener connections are bounded by `NodeConfig`; each
> propagator group's desired peers, protocol state and queues are bounded by
> `LatticePropagatorConfig`.

For a direct `NodeServer` network test, the minimum composition is explicit:

```java
NodeConfig nodeConfig = NodeConfig.localNetwork();
LatticePropagatorConfig groupConfig = LatticePropagatorConfig.create();
// The relay host's live application admits incoming values under nodeContext;
// the node only replicates what the host publishes.
NodeServer<V> node = new NodeServer<>(
    RelayHost.open(lattice, nodeStore, nodeContext), nodeConfig);
LatticePropagator group = new LatticePropagator(nodeStore, groupConfig);
group.setTransportKeyPair(nodeKey);
node.addPropagator(group);
LatticeListener transport = new LatticeListener(nodeConfig);
transport.registerPropagator(group);
transport.setSelector(connection -> group);
node.launch();
transport.launch();
```

Retain `group` and pass it to explicit pull/route APIs. Do not recover it from
the node merely to treat the first group as a privileged "primary" group.

1. Give each node its own store and key pair.
2. Use `NodeConfig.localNetwork()`. The application-owned listener binds port
   `0`; after it reports the actual OS-assigned port, `P2PNode` publishes that
   loopback endpoint in the node's signed `NodeInfo`.
3. Set an inbound propagator policy before launch. `P2PNode.serveAllInbound()` is
   suitable for a deliberately public test node.
4. Tell one node about the other with
   `nodeA.connect(nodeBKey, nodeB.getHostAddress())`. The future
   completes after B proves its node key, A's own signed `[:p2p :nodes]` record
   has been merged by B, and A has pulled and merged B's `:p2p`, `:id`, and
   currently desired complete social-owner paths.
   B discovers A from the path-scoped identity update, challenges A on the same
   full-duplex socket, then explicitly upgrades that inbound connection to an
   authenticated outbound propagation route. The bootstrap never pulls a peer's
   complete root and social admission remains follow-filtered.
   Use `nodeB.whenInboundConnectionUpgraded(nodeAKey)` when a test must wait for
   that distinct reverse-route capability before publishing in both directions.
   For three nodes, a useful discovery topology is to tell both leaves only
   about one rendezvous node. Wait until its signed registry has reached both
   leaves, then use `whenConnected` to prove the leaves discovered each other
   without another configured endpoint.
   To test late joining, converge the initial nodes before creating the newcomer,
   tell only the newcomer about the rendezvous node, and require `connect()` itself
   to deliver the existing state without a manual rendezvous-node `sync()`.
   To model a NATed late joiner, use `NodeConfig.port(-1)`: it starts no listener
   and publishes signed NodeInfo with empty `:transports`. Do not call
   `serveAllInbound()` on that leaf. Prove reverse propagation with an application
   write made after the rendezvous node's upgrade future completes; a bootstrap pull
   alone does not prove that the original outbound socket carries traffic both ways.
   For Point of Presence routing, configure each outbound-only leaf with
   `pointsOfPresence(relayKey)` before launch and opt the public node in with
   `relayMessages()`. Connect both leaves only to that relay, await both inbound
   upgrade futures on the relay, then complete a destination-side message-handler
   future from `sendMessage` or `sendPrivateMessage`. Point messages are transient
   and need no application-root `sync()`. Include a wrong-key signature case before
   a valid message on the same ordered route when testing relay authentication.
5. After an application write, call the root application's `sync()` to publish
   the authoritative node root. This schedules each propagator independently;
   its publication filter and serving-store materialisation run on that group's
   worker.
   Use the social test's independent filtered groups when testing this boundary:
   `P2PSocialSyncTest` retains the ordinary follow-aware P2P group while Bob also
   serves an infrastructure-only view from another store. A deliberately broken
   third view proves that `getStatus()` / `nextFailure()` report degradation while
   the node and healthy views continue.
   When batching several edits for one signed social owner, fork the
   `SocialUser`, apply its feed and follow actions, sync that fork once, then
   sync the application root. A `Social` fork is outside the owner boundary and
   therefore still signs each user edit inside the unpublished fork.
6. Automatic gossip is fire-and-forget. To verify it without sleeping, wait on
   `group.whenAnnounced(condition)` for the expected application state. It
   completes once this propagator group serves a value satisfying the condition
   and has queued its broadcast, after the host has merged the value and the
   node has published the root. A host sync itself guarantees only node
   publication; do not assume it completed group fan-out. Use an explicit
   `receivingServer.pull(group, connection).get(timeout)`
   only when the test is specifically about pull synchronisation. A ping only
   establishes transport ordering and does not prove acquisition is complete.
7. Close listeners before nodes, then close their stores.

Host and propagation configuration are deliberately independent. Use
`NodeConfig` for the standard listener, supplying
it independently to each component; passing it to `NodeServer` never creates a
transport. Use
`LatticePropagatorConfig` for each group's routes, protocol queue and publication
limits. `LatticePropagatorConfig.from(nodeConfig)` exists only to migrate old
combined-map callers; do not use it in new tests merely because both objects use
the same underlying CAD map representation.

Treat a node key as its P2P/transport signer, not automatically as an
application user's identity or signing key. Without an owner verifier, an owner
lattice accepts only owners that are account keys (or `did:key`), each signed by
its own key; for an indirect owner such as an address or another DID, supply a
verifier, which then decides for every owner. Give identity-sensitive tests
separate node keys and application owner/signing keys. The social cursor API
accepts canonical base DIDs and uses `DIDKeyAuthorizer` for the signer binding. Cover `did:key`, `did:convex` and
`did:web` with pinned local state or deterministic resolver fixtures—never depend
on public web resolution in a unit test. `serveAllInbound()` controls network
access and does not replace DID owner authorisation.

Remember that an `AccountKey` is a typed JVM view over a canonical 32-byte
Blob. A key stored as ordinary CAD3 application data can therefore decode as a
Blob. Domain readers should parse compatible Blob values with
`AccountKey.parse` or `AccountKey.create`; do not use `instanceof AccountKey`
as a wire-format validity check.

Never bind fixed ports and never sleep. Wait on futures, latches or another API
whose contract represents the required state.

Stop the network when finished: close listeners before nodes, then close stores.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall