Run inside the charm container

Skip Juju entirely and talk to a mounted Pebble socket directly, from a charm hook, a debug-hooks session, or against any socket path.

When borescope runs inside a Juju Kubernetes charm container, it doesn't need Juju at all. Juju mounts each workload's Pebble socket into the charm container at /charm/containers/<name>/pebble.socket, and borescope can talk to that socket directly with the real ops.pebble.Client API.

Auto-detect with --here

From a juju ssh <unit> session, a juju debug-hooks shell, or charm code, run:

$ borescope --here

borescope scans /charm/containers/ for mounted Pebble sockets. If the charm declares exactly one workload container, it connects to that one. No unit reference, no model, no Juju round-trip.

Several containers

If the charm has more than one workload container, --here can't guess which you mean, so name it:

$ borescope --here --container=workload

If you omit --container with multiple containers present, borescope lists the available names and asks you to choose one.

Files you see are the workload's, not the charm container's

When you run borescope --here inside the charm container, the prompt's filesystem commands (ls, cat, cp, push, …) see the workload container's filesystem, not the charm container's. That's the whole point — --here talks to the workload's Pebble, which serves the workload's files.

This bites most often with /tmp: a file you write in the charm container's /tmp is invisible to cat /tmp/whatever at the borescope prompt. To poke at a specific local file, push it across first:

$ borescope --here -c "push /charm/scratch.txt /tmp/scratch.txt"
$ borescope --here -c "cat /tmp/scratch.txt"

The same applies in reverse: pull /workload/path /charm/path brings a file out of the workload into the charm container's filesystem where you can juju scp it back to your workstation.

Point at a socket

To talk to a Pebble over a specific Unix socket (a workload socket at a non-standard path, or a local Pebble you're running yourself), pass --socket:

$ borescope --socket /charm/containers/workload/pebble.socket
$ borescope --socket /var/run/pebble.socket

With --socket, borescope skips Juju discovery entirely and connects straight to that socket via the HTTP API. You can still pass a unit reference for labelling (it's used for the history key and the prompt), but it isn't required.

When to use which

--here and --socket both use the direct socket transport, which is faster than going through juju ssh and works without any Juju access, but only from somewhere that can see the socket. From your workstation, use a unit reference instead. See How it reaches Pebble for how the two transports differ.