> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Console access

> The boot transcript, a screenshot, and an interactive serial session for when the network is gone.

Three endpoints, for three different situations, and each requires its own IAM
action — reading a boot log, taking a picture of the screen, and holding a
keyboard inside the guest are deliberately not the same grant.

<Tabs>
  <Tab title="Console">
    **Connect** on the instance header offers three routes: **SSH** — *From
    your terminal*, which assembles the command for you — **Serial** — *Text
    console in the browser* — and **Screenshot** — *Graphical console*.

    <Warning>
      The boot transcript has no console control. Nothing in the web
      console reads console output; **Serial** attaches a live session, and
      that needs the instance running. For a guest that failed on the way up —
      the case the transcript exists for — reading it is API only.
    </Warning>
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    GET /v1/instances/{instance_id}/console/output
    GET /v1/instances/{instance_id}/console/screenshot
    GET /v1/instances/{instance_id}/console/serial
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic compute instance console-output <instance-id> --max-bytes 65536
    basaltic compute instance console-screenshot <instance-id>
    basaltic compute instance serial-console <instance-id>
    ```

    `serial-console` opens the interactive session; the CLI sets its own
    headers, so it needs no ticket.
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    out, err := compute.New(cfg).GetConsoleOutput(ctx, instanceID, nil)
    ```

    The serial console is a WebSocket rather than a request, so the SDK does
    not wrap it — use the CLI, or the console.
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Console output — the boot transcript" icon="scroll-text">
    `GET /v1/instances/{instance_id}/console/output` returns what the guest
    wrote to its serial console during its **current boot**: a bad fstab, a
    wrong kernel, a cloud-init failure. Nothing has to be installed in the
    guest, and it works on a stopped instance — which is exactly when you need
    it.

    `max_bytes` is a ceiling you may lower, not raise: the maximum is 65536 and
    larger values are clamped to it. When the transcript is longer than what
    you asked for, its **beginning** is dropped and `truncated` is `true`. The
    end is always kept.

    The transcript resets at every start, so a crashed guest's last transcript
    is gone once it restarts — read it before you reboot. An instance that has
    never booted returns empty output, not an error.

    Requires `compute:GetConsoleOutput`.
  </Accordion>

  <Accordion title="Screenshot — what the screen shows" icon="image">
    `GET /v1/instances/{instance_id}/console/screenshot` returns a still image,
    normally `image/png`.

    This is the counterpart for everything a serial transcript cannot reach: a
    guest sitting in its boot manager, at a GRUB prompt, panicking before
    serial init, or booted from an image whose kernel was never told to log to
    the serial port. In those the transcript is empty and the screen holds the
    whole answer.

    A still, not a session — there is no remote desktop. The instance must be
    running; a stopped one has no display to capture and answers `409` rather
    than a blank frame.

    Requires `compute:GetConsoleScreenshot`.
  </Accordion>

  <Accordion title="Serial console — an interactive session" icon="terminal">
    `GET /v1/instances/{instance_id}/console/serial` upgrades to a WebSocket
    carrying an interactive session on the instance's serial port. This is the
    way in when the network is broken: a wrong kernel, a full disk, a security
    group that locked you out.

    Raw bytes in binary frames, both directions. It is a terminal, not a
    protocol — point a terminal emulator at it. Authentication rides on the
    upgrade request, signed like any other call, so there is no separate token
    step. A non-WebSocket request answers `426`.

    `backlog_bytes` replays already-written output before live output begins,
    so attaching to a quiet guest shows why it is quiet instead of an empty
    screen. Default 32768, maximum 65536, `0` disables it. The replay is the
    tail of the same recording `/console/output` serves, and the live session
    is the guest's serial port, so the join is marked with a
    `\r\n--- live ---\r\n` line: history above it, the live console below. A
    guest printing at the instant you connect may lose a few bytes at that
    line; a quiet guest — the case replay exists for — is replayed exactly.

    **One session per instance:** opening a second disconnects the first,
    rather than interleaving two people's keystrokes. A session ends after 15
    minutes idle, or 4 hours regardless, and the close frame says which.

    Requires `compute:StartSerialConsole`, and the instance to be running.

    <Note>
      This drops you at the guest's own login prompt. It is not a backdoor —
      the guest's credentials are still required, and nothing here grants
      access past what the guest itself allows.
    </Note>
  </Accordion>
</AccordionGroup>