# PortLark Agent quick start — protocol v2, CLI >= 1.4.0

Official service: https://portlark.com. This document contains no credentials.
Run on the machine/network where the user's specified local service is reachable.
Cloud agent localhost is not the user's computer. If unavailable, explain the
environment mismatch rather than claiming a working tunnel.

1. Install the official CLI, or reuse an installed CLI >= 1.4.0.
   Windows PowerShell:
     $installer = Join-Path $env:TEMP 'install-portlark.ps1'
     Invoke-WebRequest https://portlark.com/download/install-portlark.ps1 -OutFile $installer
     # Read the downloaded script, then execute it under the agent's normal permissions.
     & $installer
   Installed path: $env:LOCALAPPDATA\PortLark\bin\portlark.exe
   macOS/Linux:
     curl -fL https://portlark.com/download/install-portlark.sh -o /tmp/install-portlark.sh
     # Read the downloaded script, then execute it under the agent's normal permissions.
     sh /tmp/install-portlark.sh
   Installed path: $HOME/.local/bin/portlark
   Installers detect OS/architecture and verify SHA256 before replacing a binary.
   Use the absolute installed executable path; a shell restart/PATH change is unnecessary.
   Do not install or launch the GUI. Do not bypass agent or operating-system approvals.

2. If the user supplied a tg_boot_ code, use the existing one-hour code flow:
     portlark agent redeem --code-stdin --json
   Send the code followed by EOF through the process's standard input. Do not
   pass it as a command argument, URL query, tracked file, or log it. Never ask
   for the user's password or echo a credential in your final response.
   The result contains tunnel_id and expires_at, NOT the permanent token.
   A network failure can be retried using the same code on the same machine.
   An expired/revoked code or a code redeemed on another device requires a new
   code from https://portlark.com/dashboard/agent. Do not loop indefinitely.

   Otherwise start automatic device authorization:
     portlark agent login --json
   If state is "authorized", reuse the returned tunnel_id. Otherwise display
   verification_uri_complete as a clickable link and show user_code. The user
   signs in, checks the matching pairing code, selects a tunnel, and confirms.
   The request is valid for one hour. Do not click approval on the user's behalf
   or request their account password. The link/pairing code is not a credential;
   device secrets stay in local protected storage and never appear in output.
   After showing the link, continue with:
     portlark agent login --wait --json
   Each call polls for at most about 30 seconds and returns authorized or
   authorization_pending. While pending, keep the user informed and repeat the
   same command when appropriate; it reuses the same request and polls no faster
   than every five seconds. Denial/expiry requires user action, not blind retries.
   A fresh request for another tunnel can be started explicitly with:
     portlark agent login --new --json
   Never use --new on each poll. Network failures can retry the same login.
   Token creation and saving happen automatically after browser approval.
   Existing local authorization is reused; use up/status/stop with its tunnel ID.

3. Reuse the returned profile and start the already-authorized tunnel:
     portlark agent up --id <tunnel_id> --background --json
   No interactive setup, account login or additional tunnel creation is needed.
   up is idempotent for a running connected tunnel. It returns after connection
   readiness or a bounded timeout; the detached process continues independently
   of the agent's shell. It does not install an auto-start service for reboot.
   Only claim connected when state is "connected". local_reachable must also
   be true for the local service to accept TCP connections. For HTTP, perform
   a bounded request to public_url and report the actual status/error separately.
   Do not claim end-to-end success solely from FRP connection status; 401/403
   can be app authentication, and 502/503 can indicate an unavailable backend.
   For TCP, verify using the relevant protocol where possible; a URL is not
   necessarily a browser link. Public reachability is otherwise "not_checked".

4. Query, diagnose and stop (all commands return JSON):
     portlark agent status --id <tunnel_id> --json
     portlark agent logs --id <tunnel_id> --json
     portlark agent stop --id <tunnel_id> --json
   status reports the local managed process. stop does not delete the tunnel or
   its profile. A stopped tunnel can be restarted with up while authorization
   and its lease remain valid. Do not kill arbitrary PIDs or delete old user config.
   Repeat calls reuse the profile. Do not redeem a new code over a running tunnel;
   stop that tunnel first if the user intends to replace its device credential.

Credentials are stored in the OS user config directory under portlark/agent,
separate from legacy setup config. On Windows the directory is restricted by
ACL; on Unix it uses mode 0700 and credential files 0600. Never print these files.
The dashboard's Client Token page lists agent-<hostname> credentials, their
bound tunnel and expiry. Revocation rejects future connections and terminates
existing connections after FRP's heartbeat timeout, not necessarily instantly.

Return to the user: public address, verified connection/local/public statuses,
and the exact status/stop commands with the tunnel ID. Keep all secrets redacted.