ARNscopeDocs

EC2 Files

Last updated 13 November 2026

EC2 → Files browses the file system of an instance and opens text files, over AWS Systems Manager Session Manager. You do not need SSH, an open port, the AWS CLI or the Session Manager plugin. It is meant for the moments when you need to read a config or a log on a host, or fix one line in a config, without opening a terminal and remembering paths.

Files are read only until you turn writes on. Every save shows its diff, asks again, and keeps a backup of the old file on the instance.

Open files

  1. Open EC2, choose the profile and region, select an instance and open the Files tab.
  2. Click Open files.

Nothing connects until you click. Opening starts one Session Manager session on the instance, which AWS logs in CloudTrail like any session start, and which your account may record, including file contents. The button is disabled, with the reason, when the instance is not running (“Session Manager needs a running instance; this one is stopped.”) or your role may not start sessions.

Open files reopens the last file you had open on that instance. If it is gone, the home folder opens with a short note (“app.conf is gone.”).

What the instance needs

Who the operations run as

Files runs as root when passwordless sudo works for the session user (sudo -n), and as the session user (usually the SSM user) otherwise. The header shows which (see below), and so do the writes dialog and every save confirmation.

ARNscope turns off shell history and echo in the Files session, so its commands do not stay in the instance’s shell history. If that is not possible, a warning says so.

The header

Item Meaning
Files · name The instance’s Name tag (or its ID). Click to copy it; right-click to copy the current path, the instance ID or the Name.
Identity chip, for example Root · i-0abc1234… Who the operations run as, on which instance. It turns red while writes are on. Hover for the full identity: “Operations run as root on i-0abc… (web-1) with profile prod, account 123456789012.”
Prod ARNscope thinks this is production: the profile name contains prod, production or prd as a word, or the instance has an Environment, Env or Stage tag set to prod or production. Production gets an extra confirmation on every save.
Allow writes The writes switch. Off shows Writes off; on shows a red Writes on · N min with the minutes left.
End session Closes the Session Manager session. Unsaved changes are kept (see Unsaved changes).

Browse

Some rows are dimmed and do not open, with the reason on hover: a file or folder the session user cannot read (with its owner, group and mode, for example root:root 0640), a broken symbolic link, a device, socket or FIFO, or a name that is not valid UTF-8 (“open it in Shell”).

Read a file

The viewer shows the file name, its folder, owner, group, mode and size, and the link target when you opened a symbolic link. Toolbar: Save, Restore backup, Wrap long lines, Reload from the instance and Copy path.

File What happens
UTF-8 text up to 1 MiB Opens, and can be edited with writes on.
Text from 1 to 5 MiB Opens read only (“Larger than 1 MiB: read-only.”).
Larger than 5 MiB Not read in full, since that would be slow over Session Manager. View first 256 KB shows the start, read only.
Binary (a NUL byte in the first 8 KB) Not shown. The viewer suggests hexdump -C <path> | less in Shell.
Mixed line endings, or old-style CR line breaks Read only; edit it in Shell.
Windows (CRLF) line endings, or a UTF-8 BOM Opens and edits normally; a chip says “CRLF (kept on save)” or “UTF-8 BOM (kept on save)”.

If the file appears in the instance’s cloud-init user data, a warning stays above it: “Appears in this instance’s user data (Terraform). Host edits are lost when the instance is replaced.” Change it in your Terraform or launch template too.

Find in a file

Click in the file and press Cmd+F. The find bar has Match case (Aa), Whole word (W) and Regular expression (.*), and shows “3 of 12”. Enter goes to the next match, Shift+Enter to the previous one, Esc closes it. Find works in read-only files too.

Read only by default

A Files session starts with writes off. An editable file shows “Read-only. Turn on Writes to edit.” with a Turn on Writes button. Pressing Cmd+S with writes off points you at that button instead of saving.

Turning on writes

Use Allow writes in the header or Turn on Writes above the file. ARNscope first checks who the session runs as, then shows a native dialog, Turn on writes? (Turn on writes on production? for a production instance). The page itself cannot answer it. It names:

Click Turn on writes to continue, or Cancel to stay read only.

When writes turn off again

Edit and save

  1. With writes on, edit the file. The viewer shows Unsaved and the bar says “Editable · saves as root on web-1”.
  2. Press Cmd+S (or Save). If nothing changed: “No changes to save.”
  3. Review the diff. The file on the instance (“On the instance”) against your changes (“Your changes”), line by line.
  4. Confirm. A red bar reads, for example, “Save /etc/app/app.conf on PRODUCTION web-1 as root (1.2 KB). A backup is kept first.” Click Save (or press Cmd+Enter), or Cancel (Esc) to go back to editing.
  5. Production only: a second native dialog, Save to production?, names the path, the instance ID and Name, the profile, the user, the account and region. Click Save to production, or Cancel (“Save cancelled. Your changes are kept.”).

When it is saved: “Saved. Backup: /var/lib/arnscope/backups/… The instance keeps the last 10 backups. Restore backup is in the toolbar. The service may need a restart to apply it.” ARNscope does not restart anything; do that in Shell if the service needs it.

How a save works on the instance

Every save attempt is recorded in the local activity log with its path, size and outcome, never the content.

Backups on the instance

Files runs as Backup folder
root /var/lib/arnscope/backups (readable by root only)
the session user ~/.arnscope/backups

ARNscope keeps the newest 10 backups of each file and deletes older ones when it saves. Backups stay on the instance; nothing is copied to your Mac. Copy path gives the backup’s full path.

Restore backup

  1. Open the file and click Restore backup (the clock icon). It is disabled while you have unsaved changes: save or discard them first.
  2. The list shows “Backups of app.conf, newest first. The instance keeps the last 10.” with each backup’s save time (local) and size, and Copy path.
  3. Pick one. The diff shows the file on the instance against “This backup”.
  4. Click Restore this backup (writes must be on), then confirm. The bar reads “Restore … A backup is kept first. Restores the backup from Nov 9, 17:56.” Production asks again in the native dialog.

A restore is a save: the current file is backed up first, so you can undo a restore the same way. A backup that is not UTF-8 text under 5 MiB cannot be restored here (“Restore it in Shell.”).

Unsaved changes

Session limits and lost sessions

The built-in shell

For anything Files does not do (restarting a service, a binary file, a file with mixed line endings), use the Shell tab on the same instance, or Open shell in the instance header. Start session opens a Session Manager shell as the instance’s SSM user, inside ARNscope; End session closes it. Like Files, it starts only when you click, and AWS logs every session start in CloudTrail. ARNscope runs at most 8 shell sessions at once. The arrow next to Open shell also offers Open in your terminal and Copy SSM command.

Opened from StarRocks

On the StarRocks Logs tab, Open in Files opens the same log file here, on the node’s instance. The session still starts only when you click Open files (or right away if a Files session is already open).

Permissions

Session Manager uses your AWS identity, so there are no SSH keys or passwords to manage; access is controlled by IAM. These are the actions ARNscope uses:

What Actions
Open Files (and reopen it) ssm:StartSession, ssm:TerminateSession; ec2:DescribeInstances for the instance’s Name, account and tags (best effort)
End a Files session ssm:TerminateSession
Shell tab ssm:StartSession, ssm:TerminateSession

Browsing, reading, saving and backups travel over the open session and need no further AWS actions. What a save may change is decided on the instance: by file permissions, and by whether the session user has passwordless sudo. The instance needs an instance profile that allows Systems Manager. The IAM permission check shows which of these your role has.

Limitations

Need another mode? Write to [email protected] and tell us what you use.