Methods

Method index

arti:bootstrap_client — Tell a client to connect to the network and bootstrap itself.

Tell a client to connect to the network and bootstrap itself.

There is no need to invoke this method unless was started with the application.defer_bootstrap option set to true. By default, clients will automatically connect to the network and bootstrap themselves.

Since this method affects all applications using the Arti process, it requires administrative permissions. We may someday relax this property.

arti:describe_path — RPC method to describe the path for an object.

Describe the path(s) of a tunnel through the Tor network.

(Because of Conflux, a tunnel can have multiple paths. This method describes the members of each one.)

If include_deprecated_ids is true, the output includes deprecated node identity types, including the RSA identity. Otherwise, only non-deprecated identities are included.

arti:enter_dormant_mode — Enter "dormant mode".

Enter "dormant mode".

Currently, the only available dormant mode is "soft dormant mode", which suspends most background operations until any client request is received.

Since this method affects all applications using the Arti process, it requires administrative permissions.

Limitations

As of 2026 March, this functionality is not perfectly implemented, and likely does not interact well with onion services. Additionally, there are likely background operations that this operation doesn't cover.

This method returns a reply immediately, but it may take a little while before all of the background tasks finish their work and stop.

arti:get_client — Return the default client for a session.

Return the default client for a session.

Allocates a new ObjectID, but does not create a new underlying client object.

The returned ObjectID is a handle to a TorClient.

arti:get_client_status — Return current bootstrap and health information for a client.

Return current bootstrap and health information for a client.

arti:get_config — Return the value of part of the configuration tree.

Return the value of part of the configuration tree.

This method requires superuser access, since some options (like onion service configurations) can be sensitive.

This method can return either the value for a single option, or multiple values of the tree.

It returns the actual configuration values as used:

arti:get_proxy_info — Get a list of all the currently running proxies.

Get a list of all the currently running proxies.

This method should not be used when deciding which proxy an RPC application should connect to. Instead, the application should use arti:get_rpc_proxy_info.

arti:get_rpc_proxy_info — Get a list of the currently running proxies that are integrated with the RPC system.

Get a list of the currently running proxies that are integrated with the RPC system.

This method returns a list of proxies. The RPC application may be not be able to use all proxies from the list, and may prefer some proxies over other. When multiple proxies are equally preferred, the application SHOULD use whichever appears first in the list.

You typically won't need to invoke this method yourself: your RPC library (like arti-rpc-client-core) should take care if it for you.

arti:get_superuser_capability — Return the superuser capability for a session.

Return the superuser capability for a session.

Just as a session is the root object proving that your program has authenticated

Returns an error if this session is not authorized for superuser access, or if you have dropped superuser access via arti:remove_superuser_permission.

arti:get_tunnel — RPC method that returns the tunnel for a given object.

Return a tunnel associated with a given object.

(A tunnel is a collection of one or more circuits used to transmit data.)

Gives an error if the object is not associated with a tunnel, or if the tunnel was closed.

The returned ObjectId is a handle to a ClientTunnel. The caller should drop this ObjectId when they are done with the ClientTunnel.

arti:new_isolated_client — Create a new isolated client instance.

Create a new isolated client instance.

Returned ObjectID is a handle for a new TorClient, which is isolated from other TorClients: any streams created with the new TorClient will not share circuits with streams created with any other TorClient.

arti:new_oneshot_client — Create a new RpcOneshotClient to wait for a SOCKS request.

Create a new RpcOneshotClient to wait for a SOCKS request.

The resulting ObjectID will be a handle to an RpcOneshotClient. It can be used as the target of a single SOCKS request.

Once used for a SOCKS connect request, the object will become a handle for the underlying DataStream that was created with the request.

arti:remove_superuser_permission — Remove the superuser permission from a session.

Remove the superuser permission from a session.

Calling this method on a session ensures that future calls to arti:get_superuser_capability will return an error.`

This method does nothing if the session did not have superuser access.

This method does not drop existing superuser capability objects previously returned from arti:get_superuser_capability, or other privileged objects derived from them.

Additionally, it does not prevent you from from using auth methods to create a new session from the same connection object.

Therefore, to ensure that you cannot acquire new superuser functionality on a given connection, you must:

To ensure that an application cannot reacquire superuser permission, you also must prevent it from opening a new RPC connection to any Arti RPC connect point that allows superuser access.

arti:set_config — Change the value of a part of the configuration tree.

Change the value of a part of the configuration tree.

This method requires superuser capability, since it affects all Arti sessions.

Semantics

Arti takes its configuration from the following sources:

  1. A set of default values
  2. Configuration files on disk
  3. Command-line configuration arguments
  4. Options provided via RPC

These sources are applied in order, with later options possibly overriding earlier ones. (When a set of options is stored in a map, the maps are merged, with the later map getting precedence.) The set of options forms a tree. In the RPC system, we represent this tree as a JSON Object.

TODO: Explain all of this more clearly.

This RPC method lets you change the set of options provided via RPC. (source 4 in the list above).

When you use this method, it replaces part the the RPC configuration options at the path in the tree represented by key with the provided value.

Error behavior

This method will fail if:

If this method fails, and the configuration will (if possible[^original-state]) stay in its original state, and the method will return an error.

The current error type contains no machine-readable elements describing how it failed; we do intend to add some in the future.

NOTE: This method currently will not fail for any unrecognized options. We will, later, add options to require only recognized options, or to list unrecognized options.

[^original-state]: If arti can reject the configuration changes before it starts trying to apply them, we guarantee that the configuration will stay in its original state. Otherwise, arti will try its best to apply configuration changes on an all-or-nothing basis, but bugs or system limitations may prevent this from working completely.

Examples

Setting a single option

This invocation will disable client connections to "local" addresses over the Tor network. It will override any value for this option set in any other configuration source.

{ "key": "address_filter.allow_local_addrs", "value": false }

Setting several options at a given path.

This invocation will disable client connections to local addresses.

This replaces the whole sub-tree of RPC-provided options at address_filter. Therefore, if there are any other RPC-provided options for address_filter.*, this invocation will remove them.

We might add optional "merge" semantics (instead of replace) in the future.

{ "key": "address_filter",
  "value": { "allow_local_addrs": false } }

Clearing all RPC-provided options

This invocation will restore the configuration to the state of having no RPC-provided options:

{ "key": '', "value": {} }

It works by replacing the root of the RPC option tree with an empty Object, so that only options from the other sources will remain.

arti:watch_client_status — Run forever, delivering updates about a client's bootstrap and health information.

Run forever, delivering updates about a client's bootstrap and health information.

(This method can return updates that have no visible changes.)

arti:x_list_all_rpc_methods — Return a description of all recognized RPC methods.

Return a description of all recognized RPC methods.

Note that not every recognized method is necessarily invocable in practice. Depending on the session's access level, you might not be able to access any objects that the method might be invocable upon.

This is an experimental method. Methods starting with "x_" are extra-unstable. See RpcDispatchInformation for caveats about type names.

auth:authenticate — Authenticate on an RPC Connection, returning a new Session.

Authenticate on an RPC Connection, returning a new Session.

After connecting to Arti, clients use this method to create a Session, which they then use to access other functionality.

This method supports simple authentication schemes, where only a single pass is necessary to open a session. For now, only the auth:inherent scheme is supported here; other schemes will be implemented in the future.

See also the auth:begin_cookie method.

You typically won't need to invoke this method yourself; instead, your RPC library (such as arti-rpc-client-core) should handle it for you.

auth:cookie_begin — Begin authenticating on an RPC connection, using Cookie authentication.

Begin authenticating on an RPC connection, using Cookie authentication.

In cookie authentication, both parties prove knowledge of a shared secret, written to a file on disk. This method does not prevent MITM attacks on its own.

When cookie authentication is in use, clients use this method to begin cookie authentication by telling the RPC server a temporary nonce.

You typically won't need to invoke this method yourself; instead, your RPC library (such as arti-rpc-client-core) should handle it for you.

See rpc-cookie-sketch.md for full details of this protocol.

auth:cookie_continue — Finish cookie authentication, returning a new RPC Session.

Finish cookie authentication, returning a new RPC Session.

You typically won't need to invoke this method yourself; instead, your RPC library (such as arti-rpc-client-core) should handle it for you.

After invoking this method, the RPC library should use rpc:release to drop its reference to the CookieAuthInProgress: remember, as a rule, RPC methods other than rpc:release do not consume the objects they are invoked on.

See rpc-cookie-sketch.md for full details of this protocol.

rpc:cancel — Cancel a single request.

Cancel a single request.

Note that calling this method does not guarantee that the request is actually cancelled: the request might finish first.

What we do guarantee is that either this method returns successfully and the request is cancelled, or that this method fails and the request is not cancelled. We also guarantee that both the request and this method will finish "fairly quickly" after this method is called.

In Arti's current implementation, a cancel request is itself is not cancellable.

For more information see rpc-meta-draft.md.

rpc:clone_id — Return a new object ID referring to an existing object.

Return a new object ID referring to an existing object.

This method does not clone the underlying object itself: the new ID as well as the old ID both refer to the same object.

Releases the original object ID if the release flag is true. Otherwise, makes no change to the original object ID.

This method can be used to create a weak ID from a strong ID, or vice versa.

rpc:release — Release a single ObjectID.

Release a single ObjectID.

After calling this method, the provided ObjectID will no longer be usable, but other ObjectIDs for the same object may still exist.

Objects

Object index

arti::rpc::session::ArtiRpcSession — A top-level RPC session object.

A top-level RPC session object.

This is the first object that an RPC user receives upon authenticating; It is returned by auth:authenticate.

Other objects (TorClient,RpcDataStream, etc) are available using methods on this object. (See the list of available methods.)

This type wraps and delegates to arti_rpcserver::RpcSession, but exposes additional functionality not available at the level of arti_rpcserver, including information about configured proxies.

This ObjectID for this object can be used as the target of a SOCKS stream.

arti::rpc::superuser::RpcSuperuser — An object representing superuser access to Arti over an RPC session.

An object representing superuser access to Arti over an RPC session.

In general, RPC function is "administrative", and requires superuser access, whenever it can affect other applications.

arti_client::client::TorClient — An active client session on the Tor network.

An open client on the Tor network.

A TorClient can be used to open anonymous connections, and (eventually) perform other activities.

You can use an RpcSession as a TorClient, or use the isolated_client method to create a new TorClient whose stream will not share circuits with any other Tor client.

This ObjectID for this object can be used as the target of a SOCKS stream.

arti_rpcserver::connection::Connection — An open connection from an RPC client.

A connection to Arti.

This object is available as soon as you open a connection to Arti RPC, even before you authenticate. Its ObjectId is always "connection".

Because this object is available before authentication, it provides only those methods that you need in order to perform authentication and receive an RpcSession.

Note that a connection can only be authenticated once: If you drop the RpcSession returned by authenticating, you cannot get another one on the same connection.

arti_rpcserver::connection::auth::cookie::CookieAuthInProgress — An in-progress cookie authentication attempt.

An in-progress cookie authentication attempt.

This object is returned by auth:cookie_begin; it can be used a single time with auth:cookie_continue to finish authentication.

arti_rpcserver::session::RpcSession — An authenticated RPC session: a capability through which most other RPC functionality is available

Base type for an authenticated RPC session.

Upon successful authentication via auth:authenticate, a connection will return either a Session object of this type, or a Session object that wraps this type. All other useful objects are available via an RPC session.

This ObjectID for this object can be used as the target of a SOCKS stream.

tor_proto::client::ClientTunnel — A low-level client tunnel API.

A low-level client tunnel API.

This is a communication channel to the tunnel reactor, which manages 1 or more circuits.

Note: the tor-circmgr crates wrap this type in specialized *Tunnel types exposing only the desired subset of functionality depending on purpose and path size.

Some API calls are for single path and some for multi path. A check with the underlying reactor is done preventing for instance multi path calls to be used on a single path. Top level types should prevent this and thus this object should never be used directly.

tor_proto::client::stream::data::ClientDataStreamCtrl — An object used to control and monitor a data stream.

An object used to control and monitor a data stream.

Notes

This is a separate type from DataStream because it's useful to have multiple references to this object, whereas a DataReader and DataWriter need to have a single owner for the AsyncRead and AsyncWrite APIs to work correctly.