Sessions and tools

What each field, switch and setting does, 76 controls in all on this page. This is the text behind the ⓘ beside each label in the apps: hover or click it on the desktop (or press F1 in the field), tap it on the phone.

The line under each name gives the id the code uses for it, and says when only one of the apps has it.

Port forwarding rule

Where: Port forwarding › New rule.

What kind of tunnel?

forward.kind · also shown as “Type”

Which way traffic flows through the SSH connection. Local (-L): a port on this device reaches a service on the host’s side, for example a remote database. Remote (-R): a port on the host reaches a service on this device. Dynamic (-D): a SOCKS proxy on this device that sends any program’s traffic out through the host.

• Default: Local.

Host

forward.host

The saved host the tunnel runs through. The rule connects to it with that host’s saved login.

Rule name

forward.name

Anything that helps you recognise the rule in the list. Required, up to 256 characters.

• Example: Postgres on db

Bind address

forward.bindAddress

Which network address the listening end of the tunnel opens on: this device for a local or dynamic rule, the host for a remote rule. 127.0.0.1 means “this machine only”. 0.0.0.0 means every network the machine is on. For a remote rule the address is only a request: the server decides (its GatewayPorts setting), and most servers keep the port on their own 127.0.0.1 unless that is turned on.

• Default: 127.0.0.1 (also used when the field is left empty).
• Example: 127.0.0.1
• Caution: Anything other than 127.0.0.1 (or localhost) lets other devices on the network use the tunnel, with no password. Such a rule starts only after you approve it on this device, and again after every change.

Local port

forward.bindPort · also shown as “Remote port”

The port the tunnel listens on: on this device for a local or dynamic rule, on the host for a remote rule. This is the port your program connects to. 1 to 65535.

• Example: 5432
• Caution: Ports below 1024 usually need administrator rights, and a port already in use cannot be opened.

Destination host

forward.destHost

Where the tunnel leads. For a local rule it is seen from the host, so “localhost” means the host itself and a private name such as db.internal works. For a remote rule it is seen from this device. A dynamic rule has no destination.

• Example: localhost or db.internal

Destination port

forward.destPort

The port of the service at the destination, 1 to 65535.

• Example: 5432 for PostgreSQL, 80 for a web server

Auto-start

forward.autoStart

When the rule starts by itself: never (you start it from the list), each time its host connects, or when the app is opened. You can always start and stop it by hand.

• Default: Never: you start it by hand.
• Caution: A rule that starts at launch connects to its host without asking; if its key needs a passphrase it waits with “Needs input”. A rule from a team vault or a vault shared with you, or one that opens a port other devices can reach, does not start by itself until you approve it on this device (it waits with “Waiting for approval”), and is asked about again after every change.

Snippet

Where: Snippets › New snippet.

Name

snippet.name · also shown as “Snippet name”

What you will look for in the list. A snippet is a saved command or script you can type into any session. Required, up to 256 characters.

• Example: Restart nginx

Description

snippet.description · Desktop only

An optional line on what the snippet does, for you and whoever shares the vault.

Package

snippet.package

A folder for snippets that belong together. Packages only organise the list; they do not change how a snippet runs.

• Default: No package.

Describe what it should do

snippet.aiPrompt · also shown as “Describe the script (AI)”

Describe the task in plain words and the AI provider from Settings › AI writes the script into the field below (and a name, when the name is empty). Only this description is sent. Nothing is saved until you save.

• Example: restart nginx and tail the error log
• Caution: Generating replaces what is in the Script field. Read the result before you save or run it.

Script

snippet.script

The text typed into the session, exactly as written; several lines are fine. Write {{name}} to be asked for a value before each run, or {{name:default}} to offer a default. {{$HOST}}, {{$USER}}, {{$PORT}} and {{$NAME}} are filled in, never asked: the address, the user name it logs in as, the SSH port and the label of the host of the terminal it goes to (a local terminal has none, so give a default, as in {{$USER:root}}). Up to 65,536 characters.

• Example: sudo systemctl restart {{service:nginx}}; scp backup.tar {{$USER}}@{{$HOST}}:/tmp
• Caution: A value you are asked for is inserted as typed, with no quoting: quote it in the script if it may hold spaces. A built-in goes in as data for the shell that reads the script (sh, bash, zsh, dash, BusyBox). A command that runs its argument as a script (sh -c, ssh host ‘…’, eval, su -c, watch) or as arithmetic (let, $(( )), [[ -eq ]]) reads it again: use a plain name there. A value that needs quoting goes in only on a host where Sternway’s own check over a live connection (the one that reads its operating system) found a POSIX login shell or fish (it has to be connected when the snippet runs), and is refused where it cannot be placed safely (inside backquotes, ${…}, arithmetic, a comment or a here-document, or right after a backslash), as is a value with a control character. A backslash inside the script’s own ‘…’ stops a later quoted built-in when the snippet is typed into a terminal (whose shell may be fish even where the login shell is not) or the host’s login shell is fish: there, put a built-in outside the script’s own quotes; a run on hosts with Collect results is not affected. A host where that check cannot run or finds another shell (Windows, a network device’s CLI such as Junos, Arista EOS or NX-OS, PowerShell) takes plain values only. A built-in that starts with - is still read as an option by the command it is given to: put – before it (ssh – {{$HOST}}).

Keyboard shortcut

snippet.shortcut · Desktop only

A key combination that runs this snippet in the terminal that has the focus, as Run does: a note is pasted, and a snippet that asks for a value opens the side panel to ask. Click the field and press the keys; Backspace or Clear removes it. Kept on this device only, not with the snippet.

• Example: Ctrl+Alt+R
• Caution: Sternway’s own shortcuts come first: a key one of them uses, or another snippet’s key, is refused, and so is a key without Ctrl, Alt or Cmd (other than a function key), or Ctrl or Alt with a single key (Ctrl+C, Alt+B), which the terminal needs. The key works only while a terminal has the focus.

Kind

snippet.kind

A command is typed into the session and, with Run, followed by Enter. A note is only ever pasted: it is put at the prompt without Enter, from every place a snippet can be used (also as a host’s startup snippet), and it cannot be run in all tabs or on several hosts. Use a note for text you want to hand at the prompt and check first. A macro is a list of steps run in one terminal: it types, waits for what the host prints and answers a password prompt with a secret saved in its vault. It is never pasted, run in all tabs or on several hosts, or used as a startup snippet.

• Default: Command.
• Choices: command Command; note Note; macro Macro
• Caution: An older version of the app does not know notes: there, a note is a command that can be run. It does not show macros at all.

Steps

snippet.macroSteps

One step per line, run in order in the terminal it is started in. send types the rest of the line and Enter (variables and built-ins are filled in as in a script). wait for “text” or wait for /pattern/ waits until the output shows it, for 30 seconds or the time written after it (such as 10s, up to 3600s); a pattern is matched in time that grows only with the length of the output, so no pattern can hang the app, and it may not use back-references or look-around. send secret identity “Name” types that identity’s saved password and Enter (key “Name”: a key’s passphrase; host “Name”: a host’s saved password). pause 500ms or pause 2s waits. A line that starts with # is a comment. A step that times out stops the macro and says which line; Cancel stops it at any time.

• Example: send sudo -i wait for “password for” send secret identity “Ops admin” wait for /[#$] $/ 10s send systemctl restart nginx
• Caution: A secret is looked up only in the vault the macro is saved in, so a macro shared with a team cannot reach your personal secrets, and it is typed only into a terminal it belongs to: a host’s password into a session to that host or through it, an identity’s or key’s into a session that logs in with it; never into a local terminal. It is typed only right after a wait, and only when the line that wait found is still the terminal’s last line and is a password prompt ending in “:” (which hides what is typed); otherwise the macro stops without typing it. It is never written to the window, scrollback, recordings, logs, AI or a shared session: only to the host. A pattern that takes too much work for the output stops the macro, and so does locking the app; so does any password prompt right after a secret (the same one: a wrong password; or another, such as a password right after a passphrase), or no answer to it: nothing more is typed.

A variable of the script

snippet.variable · also shown as “Variables”

The value put where the script says {{name}}. It is inserted exactly as typed; a line break is refused.

• Default: The default written in the script, if it has one.

Name

snippetPackage.name · also shown as “New package”

The name of the package, a folder for snippets that belong together (for example “Docker” or “Backups”). The snippet list can be filtered by package, and a snippet can be in one package or none. Deleting a package keeps its snippets.

• Example: Docker

Target vault

snippet.moveVault · Desktop only

The vault to copy or move the snippet into. Everyone with access to that vault can then use it.

Hosts

snippetRun.hosts · Desktop only

The hosts to run the snippet on: the ones ticked, or (By tag rule) the hosts with the chosen tags when it runs.

How it runs

snippetRun.output · Desktop only

Open terminals: a new SSH session opens for each host, in one tab, and the script is typed there once the session is ready. Collect results: the script runs on each host over a channel of its own (four hosts at a time, nothing is typed into a terminal), and a table shows each host’s status, exit status, how long it took and the last lines it printed; Show output has the rest (up to 64 KB), and Run again on failed runs it again where it failed.

• Default: Open terminals.
• Caution: Collect results runs the script without a terminal: a command that asks a question (sudo’s password, a y/n prompt) waits for an answer that never comes, and stops after two minutes.

Save these targets as default

snippetRun.saveTargets · Desktop only

Remember the ticked hosts, or the tag rule, with the snippet, so they are chosen the next time you run it on hosts. A saved tag rule picks its hosts again each time.

• Default: Off.

Workspace name

workspace.name · Desktop only

A workspace is a saved set of tabs and split panes with the hosts in them, reopened in one go. Required, up to 256 characters.

• Example: Deploy day

SFTP: files and folders

Where: SFTP › a pane’s “+ New”, a file’s menu.

Name

sftp.name

The name of the file or folder. It cannot be empty, “.” or “..”, contain a slash, or be a name already used in this folder.

Link name

sftp.linkName · Desktop only

The name of the symbolic link: an entry that points at another file or folder, like a shortcut.

Target path

sftp.linkTarget · Desktop only

The path the link points to. It is stored as typed and not checked, so a link can point at something that does not exist yet.

• Example: /var/www/releases/current

Permissions

sftp.permissionBits · Desktop only

Who may do what with the item. Rows are the owner, the owner’s group and everyone else; columns are read, write and execute (for a folder, execute means “may enter it”). The boxes and the octal number show the same thing. With several items selected, a box with a bar is one that some of them have and some do not; only the boxes you change are applied, and every item keeps the rest of its own permissions.

Octal

sftp.octal · also shown as “Permissions (octal)”

The same permissions as three digits, one each for owner, group and others: read is 4, write 2, execute 1, added together.

• Example: 644 for a file (owner writes, all read), 755 for a folder or program
• Caution: On desktop the number sets the three basic digits for every item; a leading fourth digit (setuid, setgid, sticky) is ignored and those stay as each item has them. Mobile applies all four.

Apply to folder contents

sftp.recursive · also shown as “Apply to the contents of folders among the … items”, “Apply to contents”

Also apply the change to everything inside the folder, however deep.

• Default: Off.
• Caution: With Change set to files and folders, everything inside gets the change, which can make files executable or folders unenterable; choose Files only or Folders only to keep them apart. There is no undo.

Change

sftp.chmodOnly · Desktop only

Which of the items, and of what is inside folders when the change applies to their contents, get it: files and folders, files only, or folders only. Symbolic links are left alone by Files only and Folders only.

• Default: Files and folders.
• Example: Folders only with 755 and then Files only with 644 for a web root

Owner (uid)

sftp.uid

The numeric id of the user that owns the item. Leave it as it is to keep the owner. Changing it normally needs administrator rights on the server.

• Example: 1000

Group (gid)

sftp.gid

The numeric id of the group that owns the item. Leave it as it is to keep the group.

• Example: 33 (www-data on Debian)

Apply to all remaining conflicts

sftp.conflictAll · also shown as “Apply to all”, “Upload further saves without asking”

Use the answer you give now for every other file of this transfer that already exists, instead of being asked for each.

• Default: Off.
• Caution: Combined with Replace, the remaining existing files are overwritten without another question.

Application

sftp.openWithApp · Desktop only

The program to open the downloaded file with: its full path, or a command on your PATH. It is started with the file as its only argument. On Windows it must be a program (.exe), not a .cmd or .bat launcher: for VS Code choose Code.exe in its install folder rather than “code”.

• Example: /usr/bin/code, or C:\Program Files\Notepad++\notepad++.exe

Always use this app for .… files

sftp.openWithRemember · Desktop only

Remember this program for the file extension, so “Open with” does not ask again. The list is in Settings › SFTP › Open with.

• Default: On.

Host

openIn.host · Phone only

The saved host that files shared to Sternway from another app are uploaded to, over SFTP.

Remote directory

openIn.directory · Phone only

The folder on that host the files are uploaded into.

• Default: /tmp
• Example: /home/ada/inbox

Serial connection

Where: Hosts › New › Serial connection….

Port

serial.port · also shown as “Devices”

The serial port or USB-serial adapter to open: the cable to a router, switch or board’s console.

• Default: On desktop, “Other device…” with the path below.

Device path

serial.path · Desktop only

The system name of the serial port, for one the list does not show.

• Default: /dev/ttyUSB0, or COM1 on Windows.
• Example: /dev/ttyUSB0 on Linux, /dev/tty.usbserial-1410 on macOS, COM3 on Windows

Baud rate

serial.baud

The speed of the line in bits per second. It must match the device exactly, or you see garbage or nothing. The device’s manual says which.

• Default: 115200 on desktop, 9600 on mobile.
• Example: 9600 for most network equipment, 115200 for most development boards

Custom baud rate

serial.customBaud

A speed that is not in the list: a whole number from 50 to 4000000.

• Example: 250000

Data bits

serial.dataBits

How many bits make one character. Nearly everything uses 8.

• Default: 8.

Stop bits

serial.stopBits

How many bits mark the end of a character. Nearly everything uses 1.

• Default: 1.

Parity

serial.parity

An optional error-check bit per character. It must match the device; most use none. The common shorthand “8N1” means 8 data bits, no parity, 1 stop bit.

• Default: None.

Flow control

serial.flow

How the two ends tell each other to pause: not at all, with extra wires (RTS/CTS) or with special characters (XON/XOFF). Use what the device’s manual says; most consoles use none.

• Default: None.

Share a session

Where: A session’s menu › Share; Sessions › Join a shared session.

Link works for

share.linkWorksFor · Desktop only

How long the invite link lets guests in. When the time is up the share ends for everyone, the server closes it as well and refuses anyone who still has the link; share again for a new link. 1 hour, 24 hours or 7 days.

• Default: 24 hours.

Guests can

share.guestsCan · Desktop only

Watch only: guests see the terminal and cannot type, and nobody can be given control; the server refuses it as well. Watch, and ask you for control: a guest can ask, and types only once you give them control, which you can take back at any time.

• Default: Watch only.

Invite link

share.inviteLink

The link that lets someone watch this terminal live. Send it to them, or paste one you were sent to join. A guest needs an account on the same Sternway server and is let in by the host. The link works until the time chosen in Link works for (24 hours unless you chose otherwise), and stops for good earlier when you stop sharing or the session closes.

• Example: https://sternway.example.com/share/…#…
• Caution: The part after # is the key that decrypts the session, so send the link privately. Anyone who has it and an account on the server can ask to join.

Prompts while connecting

Where: Shown when a connection needs an answer.

Password

prompt.password

The password of your account on the server named in the title. When a server asks its own question instead (a one-time code, for example), the field shows the server’s wording with an “Asked by the server” badge.

• Caution: What you type is kept in memory for this run of the app, so reconnecting, SFTP and port forwards to the same host do not ask again. It is forgotten when the app locks, you log out or the app closes.

Hide what I type

terminal.composeHide · Phone only

For a password, a token or another secret that a program on the host asks for. The Compose field becomes a one-line password field: what you type is shown as dots, and the keyboard does not suggest it, correct it or learn it. “Insert at prompt” then types it at the prompt exactly as it is, with no Enter and never wrapped as a paste. It is switched on by itself when Compose is opened while the host is asking for a password.

• Default: Off; on when the host is asking for a password.

Save to host

prompt.savePassword

Keep this password so you are not asked next time. It is saved only once the login succeeds: on the identity the host logs in with if it uses one (so every host sharing that identity gets it), otherwise on the host.

• Default: Off.
• Caution: A saved password is stored in the vault and synced with it; in a team vault, teammates who can open the vault can use it.

Passphrase

prompt.passphrase

The passphrase that unlocks the private key named in the title. It is not your account password on the server.

Remember for this session

prompt.rememberPassphrase

Keep the passphrase in memory so this key does not ask again until the app locks, you log out or the app closes. It is never written to disk.

• Default: Off.

AI panel

Where: A terminal’s AI button (when AI is set up in Settings › AI).

What do you want to do?

aiPanel.command · also shown as “Write a command”

Describe a task in plain words and the AI provider writes a shell command for it. Only your request is sent, nothing from the terminal. The command is shown for you to edit and is never run for you.

• Example: list the 10 largest files under /var

Command (you can edit it before inserting)

aiPanel.draft

The command the AI wrote. Edit it freely, then “Insert at prompt” types it into the terminal without pressing Enter, so you still decide whether to run it.

• Caution: An AI can be wrong. Read the command, above all one that deletes or overwrites.

Your question

aiPanel.ask · also shown as “Explain or ask”

Ask about what is on screen. Your question and the text you had selected in the terminal before opening the panel (at most about 8,000 characters) are sent to the AI provider; nothing else from the terminal is.

• Example: What does this error mean?
• Caution: Do not select text that holds a password or key: the selection leaves this device.

Logs

Where: Logs (desktop).

Comment

logs.comment · Desktop only

A note shown under the log in the list, so you can find it again. Up to 4000 characters. It syncs with the log.

• Example: Database migration, 12 March

Session appearance

Where: A terminal’s menu › Session appearance….

Theme

session.theme · Desktop only

The colours of this one session. It wins over the host’s and the app’s theme until the pane closes, and is not saved anywhere.

• Default: The host’s theme, else the app’s.

Font

session.font

The typeface of this one session, for as long as it is open.

• Default: The host’s font, else the app’s.

Font size

session.fontSize

The text size of this one session, 6 to 72 pixels. Pinch-zooming a terminal on mobile changes this same value: the text follows your fingers and settles on a whole size when you let go.

• Default: The host’s size, else the app’s.

Line height

session.lineHeight

The line spacing of this one session, as a multiple of the font size, 0.8 to 2.

• Default: The host’s value, else the app’s.

Bold text

session.boldText · Phone only

Whether text a program marks as bold is drawn in a heavier weight in this one session. Off, it is drawn at normal weight, which some fonts render more cleanly at small sizes. It lasts until the session closes.

• Default: The app setting.

Bold text uses bright colours

session.boldIsBright

Whether bold text is drawn in the bright variant of its colour in this one session. It lasts until the session closes and changes no setting.

• Default: The app setting.

Smart highlighting

session.smartHighlight

Whether Sternway colours what it recognises in plain output in this one session. Turn it off for a session whose output it gets wrong; which kinds are coloured stays as set in Settings › Terminal. It lasts until the session closes and changes no setting.

• Default: The host’s setting, else the app’s.

Cursor

session.cursorStyle

The shape of the cursor in this one session: a filled block, an underline or a thin bar. A thin bar is easier to place between two characters; a block is easier to find. It lasts until the session closes and changes no setting.

• Default: The app setting.

Blinking cursor

session.cursorBlink

Whether the cursor blinks in this one session. Turn it off if the movement distracts you, or on if you lose the cursor in a busy screen. It lasts until the session closes and changes no setting.

• Default: The app setting.

Scrollback lines

session.scrollback

How many lines of past output this one session keeps, 1,000 to 100,000.

• Default: The app setting.

Bell

session.bell

What the terminal bell does in this one session: flash, make a sound (vibrate on mobile) or nothing.

• Default: The app setting.

Session recordings and exports

Where: Settings › Logs (desktop); a terminal’s menu › Record this session…; Recordings.

Largest recording (MB)

settings.recording.maxSizeMb · Desktop only

How large one recording may grow, 1 to 100 MB. A session that goes past it is not cut off: its recording is closed and a new one, part 2, goes on from there. Each part plays on its own. It is never more than the space for recordings below; lowering that space lowers this too.

• Default: 50 MB.
• More: Read more

Keep recordings for (days)

settings.recording.retentionDays · Desktop only

Recordings older than this are deleted from this device, 0 to 3650 days. 0 keeps them until you delete them (or the space below runs out). Retention runs when the app starts and after each recording ends.

• Default: 30 days.
• More: Read more

Space for recordings (MB)

settings.recording.storageMb · Desktop only

How much space all recordings on this device may take together, 16 to 65536 MB. When they take more, the oldest finished recordings are deleted until they fit. A recording still running is never deleted, and neither is the newest finished one, so the part a long session just closed is kept.

• Default: 1,024 MB.
• More: Read more

Also record what I type in this session

recording.sessionInput · Desktop only

Keeps your keystrokes in the recording as well as what the terminal showed. What you type after a prompt the app recognises (a line ending in “password:”, “passphrase:”, “PIN:” and the like, also in the common European languages, Russian, Japanese, Chinese and Korean, even when the program echoes * per key) is never kept, up to Enter, Ctrl-C or Ctrl-D.

• Default: Off: only what the terminal showed is recorded.
• Caution: Typed text can hold secrets the app cannot recognise as such: a password pasted into a command line, a token, a prompt worded differently (“Verification code:”, a language the documentation does not list) or one not at the end of the last line. Those would be recorded.
• More: Read more

File format

export.format · Desktop only

CSV opens in a spreadsheet: one row per event under a header row. NDJSON is one JSON object per line, for scripts and log tools. Both have the same fields, listed in the documentation.

• Default: CSV.
• More: Read more

From

audit.from · Desktop only

The first day to export, from its start in your computer’s time zone. Empty: from the team’s first event.

• More: Read more

To

audit.to · Desktop only

The last day to export, to its end in your computer’s time zone. Empty: up to now.

• More: Read more

Event types

audit.types · Desktop only

Only these kinds of event go into the file, separated by commas (for example member.added, vault.shared). Empty: every kind. The documentation lists them all.

• Default: Every kind.
• More: Read more