Awesome
Deprecation Notice
This project is no longer receiving updates. This project was a companion to the Aries Toolbox, which is also deprecated.
The Aries Toolbox was an invaluable tool in helping to bootstrap the Aries Ecosystem by providing ways to interact with Agents in development. This plugin in particular enabled use of the Toolbox with Aries Cloud Agent - Python (ACA-Py). Through this plugin, the toolbox provided one of the earliest UIs to an agent, enabling us to take advantage of the power of ACA-Py from the dekstop and demonstrate Agents, DIDComm, AnonCreds, and more.
This plugin was also the first of its kind, directly influencing the development of ACA-Py and plugins to ACA-Py significantly.
While the Aries Toolbox itself has been deprecated, the protocol provided by this plugin is independently notable. The protocol is effectively an Admin API to ACA-Py over DIDComm. This enables authenticated remote access to functions like Credential Issuance and Verification. If you're interested in remote management of agents with access governed by DIDs and Verifiable Credentials, this may be an excellent place to start.
If you have questions about this project or potential replacements, feel free to reach out on Hyperledger's Discord: https://discord.gg/hyperledger
Aries Cloud Agent - Python Plugin for Aries Toolbox
ACA-Py Version Compatibility
To avoid a confusing pseudo-lock-step release, this plugin is
versioned independent of ACA-Py. Plugin releases will follow standard
semver but each release will also be tagged with a mapping to an
ACA-Py version with the format acapy-X.Y.Z-J where X.Y.Z corresponds to the
ACA-Py version supported and J is an incrementing number for each new plugin
release that targets the same version of ACA-Py.
You should look for the most recent release tagged with the version of ACA-Py
you are using (with the highest value for J).
Quickstart Guide - Docker Demos
To quickly run a number of different scenarios, check out the demo instructions.
Quickstart Guide - Development-friendly Docker
For a developer friendly docker container with ACA-Py and the toolbox installed and reasonable defaults, checkout the docker instructions.
Installation
Requirements:
- Python 3.6 or higher
- ACA-Py
Setup Aries Cloud Agent - Python
If you already have an existing installation of ACA-Py, you can skip these steps and move on to plugin installation. It is also worth noting that this is not the only way to setup an ACA-Py instance. For more setup configurations, see the Aries Cloud Agent - Python repository.
First, clone ACA-Py and prepare a virtual environment:
$ git clone https://github.com/hyperledger/aries-cloudagent-python
$ cd aries-cloudagent-python
$ python3 -m venv env
$ source env/bin/activate
Install ACA-Py into the virtual environment:
$ pip install -e .
Or include the indy feature if you want to use Indy ledgers or wallets:
$ pip install -e .[indy]
Note: If you are using the indy feature, you will need to have the indy-sdk
library installed. If it's not installed, please see
Installing the SDK
Plugin Installation
Install this plugin into the virtual environment:
$ pip install git+https://github.com/hyperledger/aries-acapy-plugin-toolbox.git@main#egg=acapy_plugin_toolbox
Note: Depending on your version of pip, you may need to drop the
#egg=... to install the plugin with the above command.
Plugin Loading
Start up ACA-Py with the plugin parameter:
$ aca-py start \
-it http localhost 3000 -it ws localhost 3001 \
-ot http \
-e http://localhost:3000 ws://localhost:3001 \
--plugin acapy_plugin_toolbox
Alternatively, you may use the demo configs in demo/configs to startup ACA-Py
similarly to the demos. These demos automatically set many options, such as
ports, config options, plugins to load, etc. To do so, copy one of the config
files to the current directory and run the following command, substituting
./{config}.yml with the config file you have chosen:
aca-py start --arg-file ./{config}.yml
Generating an invitation for use with the Toolbox
By default, ACA-Py has no preexisting connections. To have our agent interact with other agents, we use the Aries Toolbox which is itself a simplified kind of agent. We need ACA-Py to emit an invitation for the toolbox to begin the connection process and bootstrap other interactions. To create an invitation that can then be loaded into the Aries Toolbox:
$ aca-py start \
-it http localhost 3000 -it ws localhost 3001 \
-ot http \
-e http://localhost:3000 ws://localhost:3001 \
--plugin acapy_plugin_toolbox \
--connections-invite --invite-label "My agent admin connection" \
--invite-metadata-json '{"group": "admin"}'
The invitation will be printed to the screen after the agent has started up and can then be pasted into the toolbox.
Groups
This plugin adds metadata to connections to distinguish between "admin
privileged" connections and connections that are not allowed to execute "admin"
operations. The invite-metadata-json flag adds this metadata to the connection
created on startup. Within the toolbox, you can create more invitations with the
"admin" group and use these invitations on other devices or individuals which
are authorized to perform administrative tasks.
Using Indy Verifiable Credentials
To use all the features of the toolbox, you'll need the indy feature installed
(as described in Setup Aries Cloud Agent -
Python). Check out the demo configurations
for Alice or Bob for a configuration using the Sovrin
BuilderNet and some reasonable defaults.
Combined HTTP+WS Transport
This plugin includes a side-loadable combined HTTP and WebSocket transport that enables accepting both HTTP and WebSocket connections on the same port. This is useful for running the agent behind a tunneling service such as ngrok that generally provides only one port-to-port tunnel at a time.
To use the HTTP+WS transport:
$ aca-py start \
-it acapy_plugin_toolbox.http_ws localhost 3000 \
-ot http \
-e http://localhost:3000 ws://localhost:3000
Note that you do not need to load any other plugins for this transport but you
can by specifying --plugin as shown in the examples above.