Roku Cloud Emulator devices

A Roku Cloud Emulator (RCE) device is a Roku that runs in the cloud instead of on your desk. The rk tool treats it as one more device kind: you register it once, then rk dev, rk ecp, rk logs, rk keysequence, rk cdp and most MCP tools reach it the same way they reach a Roku on your network. The commands that only make sense for RCE (starting and stopping a device, snapshots, and remote input) live under rk device.

RCE devices are billed while they run. Every command that starts one prints how long it may run and the most it can cost. A command that keeps running (rk dev --start with --watch or --console, or rk server after MCP device_start) stops the device it started when it exits. Anything else leaves the device running until rk device stop or its maximum runtime (see Lifecycle and cost).

Naming an RCE device

You name an RCE device with an rce: prefix wherever a command takes a device. The following table lists the selectors:

Only rk device commands reach a device that is not registered here, and of those rk logs tail --source firmware too. Everything that installs an app, talks to it, or starts it from an MCP session (rk dev, rk ecp, rk logs, rk device forward, rk device dev-id, device_start and the other MCP tools) needs the registration, since that is where the developer password is kept. For an unregistered device they fail and name rk device add --rce: with PACKAGE_DEVICE_NOT_FOUND from rk dev and MCP sideload_app, ECP_DEVICE_NOT_FOUND from rk ecp and MCP ecp (POST /api/ecp), and DEVICE_NOT_FOUND from the other rk server routes and MCP tools.

A bare name that matches both a LAN device and an RCE device selects the LAN one, with a warning on stderr naming the rce: spelling. As a result, registering an RCE device never takes a name away from a Roku on your network. You can use rce:<name> to select the RCE one. The command refuses a selector that matches more than one RCE device with DEVICE_SELECTOR_AMBIGUOUS; you can select one as rce:<id>. The --host option never takes an RCE device because an RCE device does not have an address of its own; you must use --device.

The rk device ls command lists both kinds, with a Kind and a Status column once an RCE device is registered. Status is running, pending (starting), shutdown, or unknown when RCE cannot be asked (no token, or the service did not answer). The rk device ls --rce command lists only the registered RCE devices, and rk device ls --org lists every device in your organization, registered here or not.

Before you start

You need an RCE organization and a personal access token from the RCE web UI. You can pick an expiry when you create it; the rk device set-rce-token command warns when the token is within 7 days of expiring.

Save the token once:

rk device set-rce-token                # prompts without echoing
rk device set-rce-token < token.txt    # or pipe it in

The command never takes the token as an argument; therefore, it does not end up in your shell history or process list. From a pipe, the command reads only the first line; therefore, echo "$TOKEN" | rk device set-rce-token works as well; when nothing arrives within a second, it says on stderr what it is waiting for. Surrounding whitespace is trimmed, and a token that holds anything but visible ASCII (a space, a control character, or a smart quote pasted from a document) is refused because it cannot be sent in an HTTP header. The same check applies to RK_RCE_TOKEN and to the saved file. The set-rce-token subcommand checks the token with RCE before saving and prints the user and organization it belongs to. The rk device rce-whoami command prints the same later, along with your organization's limits, and rk device clear-rce-token removes it.

The following list describes where rk keeps each file:

• The ~/roku-rce-devices.json file holds the RCE devices that you register and their developer passwords. The rk device add --rce command writes the file, and rk never reads it from a project's .roku/ directory. The ~/roku-dev-config.json file holds LAN devices only. The roku-rce-devices.example.json file shows one entry; it leaves out the developer password (password) on purpose, and you can set the password with --password-stdin instead of editing the file by hand.
• The token is kept apart, in ~/roku-rce-config.json. The rk device set-rce-token command writes it and rk device clear-rce-token removes it. The ROKU_RCE_CONFIG_PATH variable points rk at another token file, and the registrations, the session registry and rk server's start budget move with it: they are always kept in the token file's directory.
• An unreadable token file does not hide your registrations, and unreadable registrations do not hide the token. The rk device ls command lists what it could read and names the file that it could not.
• The token, the registrations, roku-rce-server-starts.json and roku-rce-mcp-session-secret (the key rk server signs MCP session ids with) are written with mode 0600 (readable by you only). On Windows that mode does not have any effect; the files are protected only by your user profile's permissions.
• The RK_RCE_TOKEN variable, when set, takes precedence over the saved token. You can use it in continuous integration (CI), where the token comes from a masked variable.
• The ~/roku-rce-sessions/ directory, next to the token file, records which rk processes on this machine started or are using each run. It does not hold any secrets, and an entry for a process that has exited is dropped. If that process owned the run (it was killed before it could stop it), the newest rk process still attached to the run owns it from then on; with none left, the run stays known as started here; therefore, rk device stop stops it without asking.

A token belongs to a user, but an organization-level token is shared by everyone who uses it: RCE, and so rk, cannot tell those people apart. A run started by a teammate with the same token shows as started by the same user, and the prompt that guards stopping someone else's run (see Stopping a device) cannot tell it is theirs.

Registering a device

The rk device add --rce command registers a device that already exists in your organization, together with the snapshot rk dev starts it from:

rk device add --rce my-tv --snapshot dev-ready --password-stdin < devpass.txt
rk device set-active rce:my-tv

The command takes the following options:

• The --snapshot <name|id> option is required. It must be ready and must not be the device's base snapshot; a snapshot with developer mode on and the installer enabled is what makes the device usable with rk dev.
• The --password-stdin option saves the device's developer (rokudev) password, read from stdin: a hidden prompt at a terminal, else the first line of the pipe. It is the password set on that device in Developer Settings; RCE devices do not inherit the LAN defaultPassword.
• The --firmware <id|name> and --max-runtime <seconds> options set what rk device start and rk dev --start use by default.
• Registering does not make the device active; rk device set-active does.

The rk device update rce:my-tv command changes the same settings later (--snapshot, --firmware, --max-runtime, --password-stdin), and also the device itself in RCE: --name (asks first; --yes skips the question, and without a terminal and without --yes it fails with RCE_RENAME_NOT_CONFIRMED), --note, --account-name, --property key=value (key= removes a property). It prints what it changed (the device in RCE, the registration, or both), or Nothing was changed. when you decline a rename; --json prints { device }, the registration as add --rce --json shows it. The rk device rm rce:my-tv command only forgets the registration; it never stops or changes the device in RCE.

Creating a device from scratch

RCE cannot delete devices; therefore, a device that you create counts against your organization's device quota permanently. For this reason, the rk device create command asks before it creates anything (--yes skips the question; without a terminal and without --yes, it refuses).

rk device create --rce my-tv --type tv

It prints the steps that turn the new device into one rk dev can use:

1. Start the device from the snapshot create names, with a firmware version from rk device firmware ls --type tv:
   rk device start rce:my-tv --snapshot <snapshot> --firmware <id>
2. Finish guided setup with remote keys, or in the RCE web viewer:
   rk device input rce:my-tv press Down Select, and rk device input rce:my-tv --text "[email protected]" for text fields.
   Linking the device to an account sends an activation email; you must open the link in it within 30 minutes.
3. Open Developer Settings and enable the installer, setting a developer password:
   rk device dev-settings rce:my-tv
4. Save a snapshot of the configured device:
   rk device snapshot create rce:my-tv --name dev-ready --wait
5. Register the device with that snapshot and password:
   rk device add --rce my-tv --snapshot dev-ready --password-stdin

You can stop the device when you are done (rk device stop rce:my-tv); later starts come up from dev-ready already configured.

Everyday use

The following commands show everyday use of an RCE device:

rk dev --start                             # Start the active device, build while it boots, install, and launch
rk dev                                     # Build and install as usual once the device is running
rk device stop                             # Stop the active device

The --device rce:<name> option targets another registered device for one command without changing the active one.

You can also start the device on its own and leave it running across several commands:

rk device start                            # Start the active device and print when it stops and the most it can cost
rk dev --console
rk ecp capture-screen --output shot.png
rk device stop

A command never starts a device that is not running; commands that need the device fail with a message that names rk dev --start or rk device start. Commands wait for a device that is still starting.

The rk device status [rce:<name>] command shows the device, its current run, its last snapshot and how many it has; --watch prints every state change until Ctrl+C. With a LAN device active and no device named, it says that it reports on RCE devices only and exits with code 0 (--json: { "device": null, "message": … }); naming a LAN device fails with DEVICE_KIND_UNSUPPORTED. The rk device runs command lists past and current runs with their runtime and cost (use --limit <n> for fewer).

What works on an RCE device

The following table shows which commands work on an RCE device and which work only on LAN devices:

A LAN-only command given an RCE device fails with DEVICE_KIND_UNSUPPORTED before contacting anything. The rk tool does not include a video viewer. It drives and observes a device through keys, ECP, logs, and screenshots, and the RCE web viewer is where you watch the device.

Lifecycle and cost

RCE bills per device-hour while a device runs; rk prints cost from the list price of $0.20 per device-hour. The figure is an estimate counted from the moment the start is requested; therefore, it includes the 1 to 2 minutes that a device spends starting. You can check your actual usage with rk device usage (your own) or rk device usage --org (the organization's; owners only), narrowed with --from <date>, --to <date> and --interval 1h|24h|1w|1mo; RCE reports those values without stating a unit, and rk shows them as given.

Every run has a maximum runtime, after which RCE stops it. It is a per-run cap, not a budget: your organization sets the largest value it accepts (rk device rce-whoami shows it), and a start asking for more is lowered to it, with a note. Billing can run past the maximum runtime: RCE ends an expired run on its own schedule, which can be minutes later.

Who stops a device depends on what started it:

On Ctrl+C, rk dev waits up to 35 seconds to stop what it started, and then for any stop request it has already sent to be answered, and exits with 130 (143 for SIGTERM); a second Ctrl+C stops waiting for the release but still waits up to 20 seconds for a stop request already sent, and a third exits at once and leaves the device to its maximum runtime. Either way, exiting before the device was released says to check it with rk device status and stop it with rk device stop, and a release that fails exits 1. With --watch in a terminal, Ctrl+C also stops a device that is still booting instead of waiting for the boot to finish. When it is unclear whether RCE accepted the start, Ctrl+C watches up to 10 seconds more for the device to come up so it can stop it, and otherwise says to check with rk device status; a run that comes up started by another user, or by another rk process on this machine, or that such a process is attached to, is left running. A device that another rk process on this machine attached to while it was starting is not stopped: that process owns the run from then on. While an rk process on this machine is stopping a run, another one cannot attach to it and fails with RCE_DEVICE_NOT_RUNNING.

The rk device start command stops a run that it started when Ctrl+C reaches it before the device is up, and exits with 130 (143 for SIGTERM); a second Ctrl+C exits once any stop request already sent has been answered, and says how to check and stop the device.

When the owning process is killed without cleaning up (SIGKILL, a crash), another rk process still attached to the run takes it over (see Before you start). With none, or when the machine lost power, the maximum runtime is the only backstop. You can set the maximum runtime to the shortest time that you need.

Stopping a device

The rk device stop [rce:<name>] command stops a device and waits until RCE reports its run ended. A run that was not started from this machine (a teammate's run, one started in the web UI, or one that rk here has only used) needs confirmation: a y/N prompt at a terminal, or --yes when there is none (a script without --yes fails with RCE_STOP_NOT_CONFIRMED). The device is read again after you answer: if the run you agreed to has ended meanwhile, nothing is stopped, and if another run has replaced it, you are asked about that one. Waiting for the stop to show never stops a run started since.

The rk device command asks every confirmation (stop, create, update --name, snapshot rm) on stderr, and only when both stdin and stdout are a terminal and --json is not set; otherwise the command refuses unless you pass --yes; therefore, piped or JSON output never waits on a question that you cannot see. Ctrl+C at the question prints Cancelled. and exits with 130, changing nothing.

Snapshots

A snapshot is the saved state a device starts from. The rk device snapshot command manages them:

rk device snapshot ls rce:my-tv
rk device snapshot show rce:my-tv dev-ready
rk device snapshot create rce:my-tv --name after-login --wait   # The device must be running
rk device snapshot update rce:my-tv after-login --note "signed in as test user"
rk device snapshot rm rce:my-tv after-login                      # Asks first; use --yes in scripts

The rm subcommand never deletes the base snapshot, the live one, or the snapshot that a registration starts from. The rk device start --snapshot <name|id> command starts once from another snapshot without changing the registration.

Sending remote input and using Developer Settings

The rk device input command sends remote keys through RCE itself; therefore, it works before developer mode is on or ECP is enabled, which rk ecp keypress needs:

rk device input rce:my-tv press Home Down Select
rk device input rce:my-tv down Right             # Hold the key
rk device input rce:my-tv up Right               # Release the key
rk device input rce:my-tv --text "hello world"
rk device input rce:my-tv ready --wait           # Wait until the device accepts input

The --text option types each character as a literal key; it cannot send /. The --delay <ms> option sets the pause between keys. The rk device dev-settings command opens the Developer Settings screen.

Once developer mode is on, the ECP commands (rk ecp keypress, rk keysequence) are the faster path and match what you would use on a LAN device. If developer mode is off, or ECP is limited, they say so and name the fix: turn it on in Developer Settings and save a new snapshot.

Logs

You can read logs from an RCE device in two ways:

• The rk logs start|get|tail|stop --device rce:my-tv and rk dev --console commands read the app's console (port 8085), as on a LAN device. The rk dev --console command reconnects on its own if the connection drops while the device runs, and exits when the run ends.
• The rk logs tail --source firmware --device rce:my-tv [--from-start] command streams the device's firmware log: system output, not your app's console. It runs locally, without rk server.

Forwarding ports

The rk device forward rce:my-tv 8085 9999 command opens a 127.0.0.1 listener for each device port and holds them until Ctrl+C or until the run ends; therefore, other tools can reach the device as if it were local. For a LAN device, it prints host:port.

• RCE bridges ports 8080, 8081, 8082, 8085, 8087, 9999 and from 49152 to 65535; the command refuses any other port, including ECP's 8060 and the installer's 80, with RCE_PORT_NOT_ALLOWED before it opens anything. The rk ecp and rk dev commands reach those two through RCE on their own.
• The listener does not take any credentials: while it is open, any process on this machine can reach the device through it.
• The forward subcommand returns once each port accepts a connection, except 8081 (the BrightScript debug port), which is not probed, since a probe there would count as a debugger connecting; a connection to it waits for the port instead.
• When the device closes a connection, the client gets what the device sent and is then closed about 2 seconds later, even if it keeps its own side open.

Screenshots

The rk ecp capture-screen command and the MCP capture_screen tool work on RCE through the device's installer rather than ECP, which RCE does not offer: an RCE device is a secure device, and its ECP does not have a screenshot endpoint. The result's source is installer. That path has the following characteristics:

• It needs the saved developer password.
• It captures only while a sideloaded app is in the foreground. On the home screen or in another app, it fails with SCREENSHOT_NOT_OK (it retries for about 2 seconds; therefore, a capture straight after a deploy still lands).
• It returns a JPEG, converted to PNG when you ask for PNG (the default).
• It returns frames whose size depends on the device, not a fixed 1920×1080.

Server and MCP

The rk server command reaches RCE devices when it has a token: started from a shell where RK_RCE_TOKEN is set, or with one saved by rk device set-rce-token (the server reads it on every request; therefore, saving one later works). Without it, the server lists RCE devices with status unknown, and the commands that only run through the server (rk logs start, rk cdp session create) refuse an RCE device and say why. Commands that can run locally fall back to your shell's token on their own.

The MCP tools that take a device accept rce:<name>, apart from the LAN-only ones in What works, which refuse it with DEVICE_KIND_UNSUPPORTED. Two tools exist only for RCE:

• The device_start tool starts a device and makes the server its owner. The server stops it on device_stop, after 15 minutes without use (RK_RCE_IDLE_STOP_MINUTES, 0 turns it off), and whenever the server exits (rk server stop, Ctrl+C, SIGTERM, SIGHUP, or its inactivity timeout). A device counts as in use while a tool call names it, while the MCP session that started it makes any call, while a CDP or debug session is open on it, while a request reaches it through one of the server's sessions (a debug call, a log read), while another process has a session on it (rk dev or rk ecp run without a server, for example), and while a command run through this server still streams from it: rk logs tail, or an rk dev the server builds. A log session the server holds open does not count on its own, since it stays open whether or not anyone reads it. Once the last of these ends, the device has the full idle time again before it is stopped. Called for a device whose stop is still under way, device_start fails with RCE_DEVICE_STOPPING.
• The server also owns, and idle-stops, a run that one of its own log or CDP sessions inherited because the process that owned it exited. Such a run does not count against the two-device limit below.
• The device_stop tool stops a device the server owns; any other device is left alone and the call names rk device stop (RCE_NOT_SERVER_OWNED). A client keyed by its Mcp-Session-Id may stop only what its own session started: another session's device, or a run the server inherited, is refused with RCE_NOT_SESSION_OWNED unless the call passes force: true. Called while that device's device_start is still under way, it cancels the start, stopping the run if it began, and the device_start fails with RCE_START_CANCELLED.
• A stop that fails leaves the device owned by the server, and still counted against its limits: the server tries again on its next check, about every 30 seconds even with the idle stop off, and at shutdown, and device_stop tries again at once. When the stop of a run one of the server's own log or CDP sessions owned fails, the server takes that run over and retries it the same way.

The server limits RCE devices as follows: one running device per MCP session, two per server, three starts per hour for each MCP session, and six starts per hour for the whole server. The server hands each client an Mcp-Session-Id when it initializes; therefore, each editor window and each rk mcp (stdio) client is a session of its own. The id is signed with a key kept on this machine; therefore, it stays valid across server restarts and any rk server here accepts it; one no server here issued (made up or altered, from another machine, or signed with a key file since deleted or replaced) is answered with HTTP 404 and MCP_SESSION_UNKNOWN, and the client opens a new session. A client that sends no id counts as one session per address, however many connections it opens, and every such client on the machine itself shares one. The hourly cap of six starts is kept in roku-rce-server-starts.json, beside the token file; therefore, restarting the server does not reset it. The per-session counts are not kept: after a restart a session starts its count again, and a client that opens a new session gets a fresh one; therefore, the server-wide limits are the hard ones. The limits guard against an agent that keeps starting devices; they are not access control. The device_start tool runs for maxRuntimeSeconds, else the registration's --max-runtime, else 30 minutes, and never more than 2 hours. Only callers on the same machine may use these two tools. Over rk mcp (stdio) they need a running rk server; without one they fail rather than start a device nothing would stop.

The server's REST routes answer an RCE failure with 409 for a state that must change first, 404 for a device, snapshot or firmware that does not exist, 400 for a request RCE refused, 429 for RCE_RATE_LIMITED and RCE_TRIAL_LIMIT, 504 for RCE_TIMEOUT, 500 for a local RCE file that cannot be read, and 502 for anything else RCE did, a rejected token included; the body's code names the error.

Environment variables

The following table lists the environment variables that affect RCE devices:

Troubleshooting

The following table lists common messages and codes with what to do:

Related documentation

• rk dev: Describes how to sideload an app, including to a Roku Cloud Emulator device with --start.
• rk device: Describes the commands that manage and query Roku devices.
• rk ecp: Describes the ECP commands for querying and controlling Roku devices.
• rk server: Describes server mode in full.