Ai Keeper/Guides/Remote access and distributed use
← All workflows
Collection 11 · Beyond one process

Remote access and distributed use

Control another Ai Keeper Mac, expose a guarded service to trusted devices, pair clients, connect nodes or agents, and separate traffic with explicit lanes.

8 workflowsBeginner-first

Find one workflow

Filter this collection by name, outcome, provider, engine, channel, mode, or command.

8 shown
Workflow 01

Control a server Mac from Client mode

Use a lighter Mac as the interface while another Ai Keeper Mac owns models and engines.

Intermediate10–20 minResult · Client sees remote runtime and chat state✓ Source-audited workflow
System Connection showing Server and Client mode plus the masked management credential.
Client mode needs the remote server address and its management API key; a single standalone Mac should stay in Server mode.
Before you start
  • A server Mac running Ai Keeper in Server mode.
  • Its reachable management URL and management API key.

  1. On the server Mac, open System > Settings > Connection, confirm Server mode, and copy the management connection details securely.

  2. On the client Mac, choose Client mode and enter the server address and management key.

  3. Save and wait for the Home connection status to become reachable.

  4. Open Runtime and Chat from the client. Confirm local-only acquisition/engine surfaces are intentionally absent.

  5. Send a harmless Chat request and inspect it on the server's Requests view.

You are done when
The client controls the remote Ready instance, and the server records the request; the client does not launch a duplicate local engine.
If something looks wrong
Used proxy API key as management keyThey protect different planes. Use the dedicated management key for remote control.
Address uses 127.0.0.1That points to the client itself. Use the server's trusted reachable address.
Workflow 02

Expose Ai Keeper to a trusted LAN safely

Move beyond loopback only after API authentication, management authentication, and firewall scope are ready.

Advanced15–30 minResult · A trusted device connects; an unauthenticated request fails✓ Source-audited workflow
System Connection showing server mode, management port, API key, and access controls.
Keep the management key masked and expose only the intended local ports to a trusted LAN.
Before you start
  • A trusted private network.
  • Strong API and management keys.
  • Permission to change macOS firewall/network exposure.

  1. Open System > Advanced > Remote Access and review the current reachability profile.

  2. Create/rotate strong keys for the proxy and management plane before changing any bind address.

  3. Enable only the interfaces/ports required and keep LAN WebSocket authentication coupled to LAN exposure.

  4. Restrict the macOS/router firewall to the trusted network or specific devices.

  5. Find this Mac's LAN address. Use the address on your active interface — not 127.0.0.1, which is unreachable from anywhere else.

    en0 is usually Wi-Fi and en1 usually Ethernet. If both are empty, that interface is not connected.

    ipconfig getifaddr en0 || ipconfig getifaddr en1
    shell

  6. From the other device, send one authenticated request against that address.

    curl http://YOUR-MAC-LAN-IP:11434/v1/models \
  -H "Authorization: Bearer $AIKEEPER_API_KEY"
    shell

  7. Now prove the door is actually locked. Send the same request with no credentials and confirm it is refused.

    This is the step people skip. If this returns a model list instead of 401, anyone on the network can use your models — stop and fix authentication before going further.

    curl -i http://YOUR-MAC-LAN-IP:11434/v1/models
    shell

  8. Re-run System > Advanced > Security Audit and confirm it does not report an exposed unauthenticated listener.

You are done when
The authorized device succeeds, unauthenticated access fails, and the Security Audit does not report an exposed unauthenticated listener.
If something looks wrong
Forwarded the port to the internetUndo it. LAN access is not safe public hosting by itself; use a reviewed VPN/reverse-proxy design if remote internet access is required.
0.0.0.0 with no keyReturn to loopback immediately and fix authentication first.
Workflow 03

Pair a trusted device

Create an explicit trust relationship for an iPhone, iPad, or another Mac client.

Intermediate5–10 minResult · The new device is listed as trusted✓ Source-audited workflow
System Advanced Device Pairing showing the companion gateway, Generate Pairing Code, code validation, and paired-device list.
Generate a short-lived code only when the trusted device is ready to enter it.
Before you start
  • Both devices are under your control and can communicate.
  • You can compare/scan the pairing challenge in person.

  1. Open System > Advanced > Device Pairing on the server Mac and start a new pairing.

  2. On the other device, open its pairing flow and scan/enter the challenge.

  3. Compare any displayed identity or confirmation code on both devices before accepting.

  4. Name the device clearly and grant only the intended scope.

  5. Test one permitted read-only action, then review the paired-device entry.

You are done when
Both devices report success, the server lists the expected identity/scope, and the read-only test works.
If something looks wrong
Unexpected pairing promptReject it and rotate/cancel the challenge. Pairing should be initiated and compared by you.
Lost deviceRevoke it immediately from Device Pairing and rotate any separate keys it possessed.
Workflow 04

Connect two Ai Keeper nodes

Discover and route work across trusted Macs while rejecting unsigned peers.

Advanced20–40 minResult · Two signed nodes see each other✓ Source-audited workflow
System Advanced Node Mesh showing its enablement, node identity, peer controls, status, and mesh-event area.
Review the exact node identity and verify each peer on this dedicated surface before routing work across the mesh.
Before you start
  • Two Ai Keeper server nodes on a trusted network.
  • Distinct node names and trust material.

  1. On each Mac, open System > Advanced > Node Mesh and assign a clear unique node identity.

  2. Exchange/approve trust material through the app's signed pairing flow. Do not accept an unsigned or unexpected peer.

  3. Enable discovery or add the explicit peer address as appropriate for the network.

  4. Wait for both nodes to show the other as reachable and authenticated.

  5. Route one harmless test job to the remote node and inspect both audit trails.

You are done when
Both nodes show an authenticated peer, the test runs on the intended remote node, and an unsigned test peer is rejected.
If something looks wrong
Duplicate node identityGive every node a unique name/identity before routing work.
Discovery crosses an untrusted networkUse explicit trusted networking and authentication; discovery is not a replacement for access control.
Workflow 05

Enable and test ACP agent communication

Exchange structured agent messages separately from MCP tool calls.

Advanced15–30 minResult · A structured ACP message round-trips✓ Source-audited workflow
System Advanced ACP Server showing enablement, host, port, authentication token, and server status.
Review the listening interface and authentication settings here before enabling ACP for another client.
Before you start
  • A trusted ACP peer or client.
  • A defined agent identity and allowed message scope.

  1. Open System > Advanced > ACP Server and review bind/auth settings.

  2. Keep it local or trusted-network only, configure authentication, and select which agents are reachable.

  3. Start the ACP service and copy its connection details securely.

  4. From the trusted peer, send one structured test message to an allowed agent.

  5. Inspect response, session identity, and Audit Trail.

You are done when
The allowed agent receives and answers the structured message; an unknown agent or unauthenticated peer is rejected.
If something looks wrong
Using ACP for toolsMCP is the tool/resource protocol; ACP is for agent communication. Configure the correct surface.
Exposed without authStop the service and correct access policy before continuing.
Workflow 06

Create a routing lane

Separate traffic by purpose, priority, or tenant so important work does not share one undifferentiated queue.

Advanced15–30 minResult · Requests are attributed to the intended lane✓ Source-audited workflow
System Advanced Lanes showing server-lane enablement and the lane-management surface.
Enable lanes only after defining how traffic should be separated, prioritized, and observed.
Before you start
  • A real need for traffic separation.
  • Known route targets and priorities.

  1. Open System > Advanced > Lanes and create a lane named for purpose, such as interactive-chat or background-indexing.

  2. Assign targets, priority/capacity, and matching rules. Keep a clear default lane.

  3. Send one request that should match the new lane and one that should remain on default.

  4. Inspect Requests and lane status to verify attribution.

  5. Document the matching rule before adding more lanes.

You are done when
Each test request appears in the expected lane and no route is stranded without a default.
If something looks wrong
Lane wedges trafficDisable the new rule and return to default, then inspect target readiness and capacity.
Too many lanesCreate them only for observable policy or capacity differences.
Workflow 07

Reach your Mac from anywhere over Tailscale

Use a private mesh network instead of opening a port on your router, and understand exactly what each button exposes.

Advanced20–40 minResult · A remote device reaches the proxy over your tailnet✓ RemoteAccessView Tailscale controls verified — including the hardcoded 8000
System Advanced Remote Access showing Tailscale detection, SSH availability, active tunnels, and guarded quick actions.
Detect tools first; Tailscale actions stay disabled until the command is installed and available.
Before you start
  • Tailscale installed and signed in on this Mac and on the remote device.
  • API-key protection already enabled — see Expose Ai Keeper to a trusted LAN safely.
  • The proxy port from System > Settings > API Access. The default is 11434.

  1. Open System > Advanced > Remote Access. If the Tailscale buttons are greyed out, Tailscale is not detected — install and sign in first, then return.

  2. Understand the two modes before clicking. Tailscale Serve exposes the app within your tailnet — only your own devices. Tailscale Funnel exposes it publicly over the internet.

    Funnel is a public endpoint. Never start it without API-key protection already proven, and prefer Serve unless you genuinely need access from a device that cannot join your tailnet.

  3. Check which port the quick actions target. The buttons read Expose Proxy (port 8000) via Tailscale Serve and the Funnel equivalent — that 8000 is fixed in the button and does not follow your configured proxy port.

    If your proxy is on the default 11434, these quick actions will not expose it. Use New Tunnel and set Local Port to your real proxy port instead.

  4. Create the tunnel explicitly: New Tunnel, set Local Port to your proxy port, then Create. Confirm it appears under Active Tunnels rather than No active tunnels.

  5. From the remote device, request the model list against the tailnet hostname. Do this before configuring any app.

    curl https://YOUR-MACHINE.YOUR-TAILNET.ts.net/v1/models \
  -H "Authorization: Bearer $AIKEEPER_API_KEY"
    shell

  6. Prove the lock holds. Repeat without credentials and confirm the request is refused.

    With Funnel this is not optional — an unauthenticated public endpoint serving your models is the worst outcome available in this app.

    curl -i https://YOUR-MACHINE.YOUR-TAILNET.ts.net/v1/models
    shell

  7. Use Stop Serve, Stop Funnel, or Stop All Tunnels when you are finished. Leave nothing exposed that you are not actively using.

You are done when
The authenticated request from the remote device returns the model list, the unauthenticated one is refused, and Active Tunnels lists only tunnels you meant to create.
If something looks wrong
The quick-action button exposed nothing usefulIt targets port 8000 regardless of your settings. Create the tunnel manually with the correct Local Port.
Funnel started but the URL 404sFunnel needs to be enabled for the tailnet in the Tailscale admin console; the app cannot grant that.
It works, and that worries youGood instinct. Run System > Advanced > Security Audit and confirm it does not report an exposed unauthenticated listener.
Workflow 08

Revoke access and rotate keys

Take access away from a device, a person, or a leaked key — and confirm it is actually gone rather than assuming.

Intermediate15–30 minResult · The revoked credential is refused✓ DevicePairingView + RemoteAccessView controls verified
System Advanced Device Pairing with the paired-device list and companion gateway status.
Revoke the exact paired device here, then rotate any separately shared management credentials.
Before you start
  • Access to this Mac.
  • A list of what you have handed out: API keys, the management key, paired devices, tunnels, channel tokens.

  1. Decide the blast radius first. Losing a laptop means revoking everything it held; retiring one script means rotating one key. Write the list down before you start clicking.

    Partial revocation is the common failure. A rotated proxy key means nothing if a paired device or an open Funnel still works.

  2. Open System > Advanced > Device Pairing and use Remove paired device for anything you no longer recognise or need. No devices paired yet. is the safe resting state.

  3. Open System > Advanced > Remote Access and use Stop All Tunnels. A revoked key does not close a tunnel you left running.

  4. Rotate the proxy API key and the management key in System > Settings > API Access and System > Settings > Connection. Store the new values in System > Advanced > Secrets, not in a note.

  5. Rotate any channel tokens and webhook secrets you issued — those are separate credentials that key rotation does not touch. See the channel and webhook walkthroughs.

  6. Verify with the old credential, not the new one. It must now be refused.

    Testing the new key only proves the new key works. Testing the old one proves the revocation happened.

    curl -i http://127.0.0.1:11434/v1/models \
  -H "Authorization: Bearer THE-OLD-KEY"
    shell

  7. Re-point the clients you still want working, one at a time, and confirm each in System > Requests.

  8. Finish in System > Advanced > Audit Trail and read what the revoked party did while they had access.

You are done when
The old credential is refused, no unexpected device remains paired, No active tunnels is shown, and every client you intended to keep still works.
If something looks wrong
The old key still worksSomething cached it, or you rotated a different key than the client uses. Check which key that client sends in System > Requests.
Everything brokeExpected if you rotated before re-pointing clients. Work through them one at a time — the list you wrote in step one is why you wrote it.
You are not sure what a device had access toAssume the widest scope. Revoke everything and re-grant deliberately; that costs an hour, the alternative costs more.

Keep going

← Lab and evaluationPrevious collectionSecurity, operations, and recovery →Next collection